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
1
MIT
Safe Omada MCP
by mariomsamy
Provides tools for interacting with TP-Link Omada controllers via the documented Open API, enabling read and (optionally, with explicit gating) write operations across 426 operations covering dashboard, clients, client insights, devices, firewall ACL/traffic, logs, WAN, threats, VPN, wireless radio, maintenance/backups, and disaster recovery. Includes safety features such as read-only defaults, dry-run previews, read-back verification, capability profiles, and audit logging.
Click on "Deploy 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 MCPlist all connected clients on my Omada 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.
What this is
A merged, safety-first MCP server for TP-Link Omada controllers, built from a survey of 23 public Omada MCP projects (comparison, merge notes).
Base: gaspareduard/Omada-mcp ("safe-omada-mcp"), itself a hardened fork of MiguelTVMS/tplink-omada-mcp.
Added: 54 tools ported from realtydev, aljopro, Zesty0wl and daniel-k, each matched to a documented Open API operation (ported and skipped), and eight agent skills adapted from ChenyqThu/omada-skill and kaviththiranga/omada-mcp-server plus two new ones (skills).
Surface: 426 operations (337 read, 89 write) plus 4 discovery tools; 28 deprecated aliases are hidden by default.
Credits: every source and what was taken from it is listed in Credits and NOTICE.md.
Quick start (Claude Desktop / Claude Code)
npm ci && npm run build # Node.js 24+Claude Desktop (claude_desktop_config.json) or a Claude Code project
.mcp.json (Claude Code expands ${VAR} from your shell, so the file
holds no secrets):
{
"mcpServers": {
"safe-omada": {
"command": "node",
"args": ["/absolute/path/to/safe-omada-mcp/dist/index.js"],
"env": {
"OMADA_BASE_URL": "${OMADA_BASE_URL}",
"OMADA_CLIENT_ID": "${OMADA_CLIENT_ID}",
"OMADA_CLIENT_SECRET": "${OMADA_CLIENT_SECRET}",
"OMADA_OMADAC_ID": "${OMADA_OMADAC_ID}",
"OMADA_STRICT_SSL": "true",
"OMADA_CAPABILITY_PROFILE": "safe-read"
}
}
}
}Claude Code one-liner:
claude mcp add safe-omada --scope user \
-e OMADA_BASE_URL=https://<controller-host>:8043 -e OMADA_CLIENT_ID=<client-id> \
-e OMADA_CLIENT_SECRET=<client-secret> -e OMADA_OMADAC_ID=<omadac-id> \
-e OMADA_STRICT_SSL=true -e OMADA_CAPABILITY_PROFILE=safe-read \
-- node /absolute/path/to/safe-omada-mcp/dist/index.jsClaude Desktop does not expand ${VAR}; put placeholder-replaced values
there and protect the file. A Docker variant is in the Quick Start below.
Install for your AI agent
docs/INSTALL.md has exact configuration for Claude
Code (claude mcp add and .mcp.json), Claude Desktop, Codex CLI
(~/.codex/config.toml, [mcp_servers.omada]), Cursor
(~/.cursor/mcp.json or .cursor/mcp.json), Gemini CLI, VS Code /
GitHub Copilot (.vscode/mcp.json), Windsurf, Cline and OpenCode, plus
a hardened Docker variant. It also explains how to create Open API
credentials (Global View > Settings > Platform Integration > Open API,
client mode, start with a viewer role), why OMADA_STRICT_SSL stays
true (use OMADA_CA_FILE for self-signed controllers), and where the
skills go for each agent (~/.claude/skills, AGENTS.md,
.cursor/rules).
Capability profiles at a glance
Profile | What is registered | Typical use |
| Reads for dashboard, clients, client insights, devices, firewall ACL/traffic | First install, monitoring |
| Every read tool, no write tool | Read-only skills (audit, triage, troubleshooting) |
| Reads for dashboard, clients, client insights, devices, logs, WAN, threats, VPN; writes for clients and maintenance (backups) | Day-to-day operations |
| All categories, read and write, except recovery | Planned configuration changes |
| Restore tools; also need | Operator-led disaster recovery |
OMADA_TOOL_CATEGORIES replaces the profile defaults; grant the
narrowest categories you need (for example all:r,wireless-radio:rw).
Safety guarantees
Read-only by default. Write tools are not even registered unless the profile or categories grant them.
Dry run by default. Every write returns a preview (
planned) unless called withdryRun: false.Read-back. Key writes verify the controller state afterwards and report
verified,mismatch,unknown,unverifiableorpartial; others reportsubmittedand should be read back (see the omada-safe-change skill).Recovery isolation. Restores need an explicit
recovery:rwgrant plusconfirmDangerous: true; neitheradminnorall:rwincludes it.No raw API tool, no private web API, no header-supplied credentials; credentials come only from the environment.
Redaction of secrets in logs and tool results; audit events for every mutation.
stdio first. HTTP is lab-only, loopback-only and needs two explicit opt-in variables. TLS verification is on by default.
These are server-side controls. They do not replace human approval: configure your agent to ask before running write tools.
Skills
Eight skills in skills/ teach an agent whole workflows with
this server: omada-network-audit (read-only health and security
review), omada-safe-change (dry-run -> review -> apply -> read-back),
omada-wifi-troubleshoot, omada-roaming-dfs, omada-alert-triage,
omada-support-assist, omada-bulk-site-onboard and
omada-guest-portal-wizard. For Claude Code:
cp -R skills/omada-* ~/.claude/skills/. Details: docs/SKILLS.md.
Documentation
Document | Contents |
Agent configuration, credentials, profiles, TLS | |
Skill index and installation | |
The 23 surveyed repositories and verdicts | |
What was merged, what was fixed, known limitations | |
Ported and skipped tools | |
Security model | |
Operator guide | |
Controller and device support | |
Contributor guide for AI coding agents |
Related MCP server: tplink-omada-mcp
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
Uses documented Open API routes; controller/device validation is operation-specific (see support matrix)
0.19 release candidate
This branch prepares 0.19.0-rc.1. Write previews, compact discovery, diagnostics and reliability changes are described in the migration guide. Stable write-tool release awaits disposable-controller and hardware validation; latest remains the existing stable version.
Quick Start
Option 1: Use with Claude Desktop via Docker
Pull or build an image:
docker build -t omada-mcp:local .If 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", "omada-mcp:local" ] } } }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 \
omada-mcp:localOption 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. When omitted and no tool-level site ID is supplied, a single available site is selected automatically; zero or multiple sites return an error. |
| No |
| Enforce TLS certificate validation |
| No | - | PEM private CA bundle path; retains hostname verification. Mount the file read-only in Docker. |
| No |
| HTTP timeout in milliseconds |
Capability and Logging
Variable | Required | Default | Description |
| No |
| Built-in profile: |
| No | profile default | Explicit category override; recovery requires |
| No |
|
|
| No |
| Include deprecated aliases |
| No |
| Expose only bounded |
| No |
|
|
| No |
|
|
Capability Profiles
Profile | Intended use |
| Default read-only operational visibility |
| Client operations and maintenance writes, excluding recovery |
| All implemented categories except recovery |
| Deprecated alias for |
OMADA_TOOL_CATEGORIES replaces profile defaults. Restore tools require explicit recovery:rw; neither admin, compatibility, nor all:rw grants recovery.
Mutation previews and recovery
Writes default to dryRun: true. Review the preview and explicitly pass dryRun: false to apply. submitted means the controller accepted a request; only verified indicates a matching readback. See the 0.19 migration guide for verification limits and partial outcomes.
Restore tools also require confirmDangerous: true. This is an argument check, not enforced human approval or a stateful second-call protocol. Configure approvals in the MCP host and grant recovery:rw only when recovery is intended.
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
0.19 workflows and discovery
Tool | Description |
| Composes dashboard, channel, interference and retry evidence with timestamps, missing sections and bounded review heuristics. Read-only. |
| Reads recent event, alert and audit pages plus log settings; distinguishes unavailable data from empty results and reports incomplete history. |
| Resolves a camera client and reads its detail/session evidence; reports missing data and network drilldowns without claiming to diagnose Frigate inference. |
| Previews or updates one supported AP band with advertised channel/width validation, preserved sibling settings and bounded readback verification. |
| Previews or updates SSID name, broadcast visibility, guest status or sharing policy while preserving required security fields. Broadcast visibility is not SSID enable/disable. |
| Previews or updates name, status, PoE, profile or override for 1–32 explicit ports. Checks existence, guards known LAG disruption and reports per-port verification/partial completion. |
| Searches only enabled operations by name, description or category. |
| Returns an enabled operation's exact argument schema and permission. |
| Reports version, effective catalog, profile and validation limits. |
| Compact mode only: invokes an enabled operation through its existing schema and handler. |
Each category below is collapsed by default. Click to expand and see the full tool list, split into read and write tools.
Ported operations
Tools ported from sibling MIT-licensed Omada MCP projects (see NOTICE.md). Every route was re-verified against the bundled OpenAPI snapshots in docs/openapi/; candidates without a documented route, duplicates of existing tools and private-API tools were skipped and are listed in docs/porting-skipped.md. All writes default to dryRun: true. Tools marked destructive carry destructiveHint and sit in categories that only the admin profile (or an explicit OMADA_TOOL_CATEGORIES grant) enables; ops-write only grants the non-destructive updateClient from this set.
Tool | Category | Risk | Description |
|
| read | Gets the site WLAN experience index from recent WLAN optimization scans. |
|
| read | Lists RF planning (WLAN optimization) history entries for a site. |
|
| read | Gets one RF planning history entry, including the recommended and previous configuration. |
|
| read | Lists device reboot schedules configured for a site. |
|
| read | Reports this MCP server package name/version and Node.js runtime. Local only; no controller request. |
Tool | Category | Risk | Description |
|
| write | Starts adoption of a pending device; optional device credentials are never echoed. |
|
| destructive | Starts a cable test on explicit switch ports (may briefly interrupt link); read results with getCableTestFullResults. |
|
| destructive | Starts an online firmware upgrade of one device (device reboots); preview shows current firmware info. Admin profile only. |
|
| destructive | Batch modifies switch VLAN interfaces with a preview of the current list. Admin profile only. |
|
| destructive | Connects or disconnects a gateway WAN port; disconnecting can take the site offline. Admin profile only. |
|
| destructive | Modifies one WAN port's settings with a preview of the current WAN configuration. Admin profile only. |
|
| write | Enables or disables the site-wide device LED setting with preview. |
|
| write | Sets a client's display name with dry-run preview. |
|
| write | Creates a LAN network with dry-run preview. |
|
| destructive | Updates an existing LAN network after an existence preflight; preview shows the current record. Admin profile only. |
|
| destructive | Deletes an existing LAN network after an existence preflight. Admin profile only. |
|
| write | Creates a LAN (switch port) profile with dry-run preview. |
|
| destructive | Updates an existing LAN (switch port) profile after an existence preflight; preview shows the current record. Admin profile only. |
|
| destructive | Creates a NAT port forwarding rule with dry-run preview. Admin profile only. |
|
| destructive | Updates an existing NAT port forwarding rule after an existence preflight; preview shows the current record. Admin profile only. |
|
| destructive | Deletes an existing NAT port forwarding rule after an existence preflight. Admin profile only. |
|
| destructive | Creates a static route with dry-run preview. Admin profile only. |
|
| destructive | Updates an existing static route after an existence preflight; preview shows the current record. Admin profile only. |
|
| destructive | Deletes an existing static route after an existence preflight. Admin profile only. |
|
| write | Creates an SSID in a WLAN group with dry-run preview; secrets are redacted from output. |
|
| destructive | Deletes an SSID (clients disconnect); preview shows the current SSID detail. Admin profile only. |
|
| write | Updates SSID Hotspot 2.0 with a preview of the current SSID detail. |
|
| destructive | Updates SSID MAC filter settings with a preview of the current SSID detail. Admin profile only. |
|
| write | Updates SSID multicast/broadcast management settings with a preview of the current SSID detail. |
|
| write | Updates SSID 802.11 data rate control settings with a preview of the current SSID detail. |
|
| write | Updates SSID SSID and per-client rate limit settings with a preview of the current SSID detail. |
|
| destructive | Updates SSID WLAN schedule with a preview of the current SSID detail. Admin profile only. |
|
| write | Updates the site band steering setting with a preview of the current setting. |
|
| write | Updates the site beacon control and airtime fairness setting with a preview of the current setting. |
|
| destructive | Updates the site mesh setting with a preview of the current setting. Admin profile only. |
|
| write | Updates the site roaming setting with a preview of the current setting. |
|
| destructive | Starts WLAN (RF planning) optimization; can change AP channels/power. Admin profile only. |
|
| write | Cancels a running WLAN (RF planning) optimization. |
|
| destructive | Applies the recommended or previous configuration from an RF planning history entry. Admin profile only. |
|
| destructive | Deletes an RF planning history entry. Admin profile only. |
|
| write | Modifies the RF planning deploy configuration with a preview of the current configuration. |
|
| destructive | Creates a site reboot schedule (it schedules device reboots). Admin profile only. |
|
| destructive | Replaces an existing site reboot schedule after an existence preflight. Admin profile only. |
|
| destructive | Deletes an existing site reboot schedule after an existence preflight. Admin profile only. |
|
| destructive | Creates a site PoE schedule (it powers PoE ports off outside the time range). Admin profile only. |
|
| destructive | Replaces an existing site PoE schedule after an existence preflight. Admin profile only. |
|
| destructive | Deletes an existing site PoE schedule after an existence preflight. Admin profile only. |
|
| destructive | Modifies the site IDS/IPS configuration with a preview of the current configuration. Admin profile only. |
|
| destructive | Permanently deletes alert logs (site or global); broad selections need explicit confirmation. Admin profile only. |
|
| destructive | Permanently deletes event logs (site or global); broad selections need explicit confirmation. Admin profile only. |
|
| write | Marks site alert logs as resolved; broad selections need explicit confirmation. |
|
| destructive | Resets log notification settings to defaults (site or global); preview shows current settings. Admin profile only. |
|
| write | Modifies log notification settings (site or global, v2 route) with a preview of the current settings. |
|
| destructive | Modifies audit log notification settings (site or global) with preview. Admin profile only. |
Site & Client
Site listing, client monitoring, and client-level operational controls (rate limits, block/unblock, reconnect).
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. |
Tool | Description |
| 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. |
Tool | Description |
| Reboots a managed device with an auditable mutation summary. |
| Changes a device LED state with an auditable mutation summary. |
Device
Device inventory, per-device detail (switches, gateways, APs), firmware, cable tests, and device configuration.
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 |
| 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 |
Tool | Description |
| 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 |
| 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
WAN/LAN configuration, SSIDs, WLAN groups, routing, NAT, DHCP, DNS, firewall settings, bandwidth control, and related network services.
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. |
| Gets VPN settings for a site. |
| Lists site-to-site VPN configurations. |
| [DEPRECATED] Use |
| Lists gateway (OSG) ACL rules. |
| Lists access point (EAP) ACL rules. |
| [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). |
| Gets IP-MAC binding entries (paginated). |
| Gets IP-MAC binding global toggle setting. |
| Gets global bandwidth control configuration. |
| Gets bandwidth control rules (paginated). |
| 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. |
| 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. |
Tool | Description |
| Updates site firewall settings with dry-run preview using the official Omada Open API firewall endpoint. |
| Updates the gateway ACL mode ( |
| 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. |
| 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. |
| Creates a switch (OSW) ACL rule with dry-run preview using the official Omada SwitchACLConfig schema. |
| Updates a switch (OSW) ACL rule with dry-run preview after confirming the ACL exists. |
| Deletes an ACL rule with dry-run preview after confirming the ACL exists. |
| 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. |
| 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. |
| 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. |
Firewall & ACL
802.1X authentication and RADIUS proxy settings.
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
Traffic shaping, QoS policies, application control, URL filtering, and MAC filtering.
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
Intrusion detection and prevention system configuration.
Tool | Description |
| [DEPRECATED] Use |
Security & Threat Management
Global threat intelligence, IPS alerts, and top-threat summaries.
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
Site dashboard widgets: WiFi and switch summaries, PoE usage, CPU/memory top-N, traffic activities, VPN tunnel stats, and RF analytics.
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
Site-level security insights: threat events, WIDS, rogue AP detection, and VPN tunnel stats.
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
Site-to-site and client-to-site VPN configuration, tunnel details, and user management.
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
RADIUS, PPSK, service, QoS, schedule, group policy, VLAN, user role, and portal 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
Site-level and global event, alert, and audit 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
Controller-level settings: certificates, ports, data retention, telemetry, and global dashboard.
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
Controller and site backups, restores, and rogue AP exports.
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. |
Tool | Description |
| 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
User and role management for the controller.
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
Cloud access, MFA, and remote binding status.
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
PoE, port, reboot, and firmware upgrade 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. |
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. |
|
| List switch ACL rules. |
|
| Create a switch ACL with dry-run support. |
|
| Update a switch 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 |
|
Credits
This project stands on the work of the authors below. Licenses and copyright lines are in NOTICE.md; the full survey is in docs/COMPARISON.md.
Repository | Author | License | What we took |
gaspareduard | MIT | Base project (code): safety model, capability profiles, catalog, tools, tests, CI | |
João Miguel Tabosa Vaz Marques Silva | MIT | Code via the base: original tool surface and registry pattern | |
Alex Gibson (realtydev) | MIT | Code ported: write tools (port forwards, routes, WAN, IPS and others), | |
aljopro | MIT | Code ported: | |
Zesty0wl | MIT | Code ported (re-implemented on Open API routes): PoE and reboot schedules | |
daniel-k | MIT | Code ported: RF planning, SSID sections, log and notification writes | |
Chen Yuanquan | MIT | Skills: five skills adapted and rewritten for this server | |
Kavith Lokuhewage | MIT | Skills: roaming/DFS knowledge as | |
dfla-me | MIT | Idea only: whole-object edits and override detection in | |
Mark Arslan | MIT | Idea only: controller quirks and data-honesty rules; certificate pinning planned | |
samhaque | MIT | Idea only: search/describe catalog pattern, HTTP hardening ideas | |
samhaque | Apache-2.0 | Idea only: triage -> investigate pattern | |
thalisantunes | Apache-2.0 | Idea only: write-guard and audit design, hardware quirks (in skills) | |
ricardo-david-francisco | MIT | Idea only: encodings, error-code table and hardware findings (in skills) | |
sirfyyn | Apache-2.0 | Idea only: read-only facade for autonomous agents | |
mballoni | GPL-3.0-only | Idea only: fixed scoring rubric with baseline, re-designed independently for | |
RonaldPhilipsen | none | Idea only: registration-time gating, spec-hash pinning; no code (no license) | |
jkohen | none | Rejected: no license file, nothing copied | |
wonjo-linc | none | Rejected: no license file, nothing copied | |
kohlsalem | none | Rejected: no license; nothing beyond existing reads | |
Omada A/S | Omada Technology Preview License | Excluded: Omada Identity product, unrelated to TP-Link | |
walkerpauldavid | none found | Excluded: Omada Identity product, unrelated to TP-Link | |
bforejt | none | Excluded: empty repository |
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
113 toolsdescribeOperationARead-only
Get the exact argument schema and permission for an enabled tool. Unavailable tools cannot be inspected or executed.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with them. It adds real value beyond the annotations by disclosing the enabled-only restriction and that unavailable tools cannot be inspected, which an agent needs before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler; the capability is front-loaded and the constraint follows immediately. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description covers what is returned at a high level (argument schema and permission) and the precondition. It stops short of describing the response shape, which matters somewhat since no output schema exists.
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 0% for the single required 'name' parameter, so the description must carry the meaning. It implies the value identifies an enabled tool, but does not specify the name format, source (e.g., output of searchOperations), or case sensitivity.
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 names the resources returned: the exact argument schema and permission for a tool. It is distinguishable from the searchOperations sibling by scoping to a single already-enabled tool, though it never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a hard precondition ('Unavailable tools cannot be inspected or executed'), which implicitly tells the agent to discover enabled tool names first, but it never says to use searchOperations for that discovery or explains the failure behavior beyond unavailability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
diagnoseCameraConnectivityARead-only
Read-only camera network evidence by IP, hostname or MAC: current connection, VLAN/signal details and recent sessions. Does not test video decoding/inference or power-cycle a camera.
| 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. | |
| identifier | Yes |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that. It adds useful behavioral context beyond the annotations: the categories of evidence returned and the boundary that it will not perform active tests or power-cycle the device. It does not mention permissions, latency, or pagination of 'recent sessions', which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with no filler. The capability is front-loaded and the negative scope follows, which is the right order for an agent scanning the definition.
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 no output schema, the description appropriately names the kinds of evidence returned (connection state, VLAN/signal, recent sessions), which is enough to decide whether to call it. It does not describe the shape of the response or how 'recent sessions' is bounded, a minor gap for a two-parameter 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 coverage is only 50% because the required 'identifier' parameter has no schema description, so the description carries real weight by specifying that it accepts an IP, a hostname, or a MAC address. That is precisely the missing meaning. The siteId parameter is left to the schema, which documents it well.
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?
States a specific verb and resource ('Read-only camera network evidence by IP, hostname or MAC') and enumerates what the evidence covers (current connection, VLAN/signal details, recent sessions). It is clearly a diagnostic read rather than a configuration tool, though it does not name a specific sibling (e.g. diagnoseClient) it should be preferred over.
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?
Gives clear conditions for use (identify the camera by IP, hostname or MAC) and explicit scope exclusions: it does not test video decoding/inference and does not power-cycle a camera. What is missing is a named alternative for those excluded cases, so the agent knows where to go instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
diagnoseClientARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Optional site ID. Uses default site if omitted. | |
| 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. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: this is a single-call aggregation of three data sources and history is capped at the last 10 sessions, which tells the agent about scope and truncation. It omits any note on lookup failure behavior or output shape, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each doing distinct work: what it returns, when to reach for it, what input it takes. The composite scope is front-loaded and there is no 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?
With no output schema, the description carries the burden of telling the agent what comes back, and it does so by listing the three data components and the 10-session history window. It stops short of describing how those components are structured or what happens when the identifier matches nothing, which is a minor gap for a read-only diagnostic.
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 both parameters are already documented in structured form, making the baseline 3. The description restates that MAC, IP, or hostname are accepted but adds no new syntax or constraint detail, and it never mentions the optional siteId 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 names a specific composite resource and enumerates exactly what it aggregates: current connection status, detailed info (VLAN, signal, rate limit, group policy), and the last 10 sessions. This clearly separates it from siblings like getClientDetail or getGridClientHistory, which return only one slice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear when-to-use triggers — cannot connect, poor performance, repeated disconnects — which is exactly the troubleshooting context for a composite tool. It does not explicitly name alternatives or say when to prefer the narrower sibling calls instead, which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getAclConfigTypeSettingBRead-only
Get the ACL configuration type setting for the site gateway (L2 or L3 mode). Determines how ACL rules are evaluated for traffic.
| 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. |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the description need not repeat it. The description adds modest value by explaining what the setting means semantically (how ACL rules are evaluated for traffic) and that the answer is an L2/L3 mode, but says nothing about response shape, multi-site behavior, or what happens when the gateway lacks ACL support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the verb+resource and followed by a single clarifying clause about semantics. The second sentence earns its place by explaining what the setting governs, though it borders on restating the first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-parameter read tool this is close to sufficient, and the mention of L2/L3 mode partially compensates for the absence of an output schema. However, with no output schema the agent still cannot tell the exact return shape (bare enum versus an object containing site and mode), and edge cases such as non-gateway sites or omitted siteId outcomes are unaddressed.
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 a single optional siteId that already documents its pattern, the OMADA_SITE_ID default fallback, and the listSites discovery path. The description adds nothing about parameters, so the baseline of 3 applies — the schema does all the work here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource (get the ACL configuration type setting) and scopes it to the site gateway, further clarifying the value domain as L2 or L3 mode. This distinguishes it reasonably well from siblings that return ACL rule lists (listOsgAcls, getOsgCustomAclList) or general firewall config (getFirewallSetting), though it never names those alternatives explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer it should call this when it needs to know whether ACLs are evaluated in L2 or L3 mode. There is no stated when-to-use condition, no prerequisite (e.g., gateway must support ACLs), and no explicit pointer to the sibling ACL tools that answer different questions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getAllDeviceBySiteARead-only
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.
| 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. |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered by structured data. The description adds real behavioral value by stating that results include offline and disconnected devices (i.e., no active-state filtering). It says nothing about pagination, result size, or ordering, which are the remaining behavioral unknowns for a full-inventory listing.
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 short sentences, front-loaded with the scope, then the sibling differentiation, then the use case. The second sentence ('returns the full device inventory') partly restates the offline/disconnected clause, a minor redundancy that keeps it from a 5.
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 single-parameter, optional-argument read tool with annotations covering safety, the description covers what is listed, its scope, and when to prefer it. With no output schema, a brief note on return shape or volume would have closed the last 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 description coverage is 100% and the siteId property already documents the default-from-config behavior and the listSites discovery path. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Get all devices in a site') and immediately bounds the scope with 'including offline and disconnected devices'. It explicitly distinguishes itself from a named sibling, listDevices, so an agent can pick between them without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names the alternative (listDevices) and the condition that separates them ('may filter to active-only'), plus a concrete use case ('auditing what hardware is registered to a site'). The routing cue is hedged with 'may', so the exclusion is slightly softer than an explicit when-not statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApDetailARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A4.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that the response is a composite of configuration plus live status, but says nothing about latency, partial availability when an AP is offline, or error behavior for an unknown MAC.
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 field inventory is front-loaded so an agent knows immediately whether this tool answers its question, and the prerequisite hint follows. No filler or restatement of the tool name.
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?
There is no output schema, but the description compensates by naming the principal returned fields, and the annotations cover the read-only safety profile while the schema covers both parameters. Nothing material is missing for a two-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents both apMac (with pattern and example) and siteId (with the OMADA_SITE_ID default and listSites pointer). The description's 'Use listDevices to get the apMac' merely restates the schema's apMac description, adding no new parameter meaning.
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?
States a specific verb ('Fetch') and resource ('full configuration and status for a specific access point') and enumerates the returned data (model, firmware, CPU/memory, client count, SSIDs, uptime, mesh status). That enumeration implicitly separates it from the many narrow siblings such as getApRadios, getApQosConfig and getApGeneralConfig, which return only one slice of AP data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete prerequisite workflow: 'Use listDevices to get the apMac,' which is exactly the step an agent needs before calling. It does not state when to prefer the narrow config tools (getApRadios, getApVlanConfig) over this aggregate view, so an explicit exclusion is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApGeneralConfigARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: this returns persisted configuration rather than live runtime state, and it names the specific categories of values returned, which helps an agent interpret the result.
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 short sentences, front-loaded with the purpose and return contents, then the disambiguation. No filler, no restating of the tool name, and the sibling reference comes after the essential information rather than burying it.
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 no output schema, the description takes on the job of telling the agent what comes back, and it does so by enumerating representative fields plus the qualifier "other global AP parameters." Combined with 100% schema coverage on inputs and safety annotations, an agent has what it needs to call this correctly; only the exact response shape remains unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully documented in the schema (100% coverage), including MAC format, an example value, the siteId default behavior, and pointers to listDevices and listSites. The description adds nothing about apMac or siteId beyond what the schema already says, so the 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 uses a specific verb and resource ("Get general configuration for an access point") and then enumerates the concrete fields returned — device name, LED settings, country/region, management VLAN, bandwidth limits — so an agent knows exactly what class of data this yields versus siblings like getApRadios 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly routes the agent away from a sibling by naming the condition that selects it: "Use getApDetail for runtime status; this returns stored configuration." That is a clear when-to-use-this-instead statement, but no guidance is given relative to the many other AP config tools (getApUplinkConfig, getApSnmpConfig, getApQosConfig), which is why this falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApIpv6ConfigBRead-only
Get IPv6 configuration for a specific access point.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. Beyond that the description adds nothing behavioral: it does not say what the returned IPv6 config contains, what happens if IPv6 is disabled or the AP is unreachable, or whether site scoping changes results. It essentially restates 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?
A single front-loaded sentence with no filler, hedging, or repetition. Nothing in it is wasted, though there is also very little of it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only getter with full schema coverage and annotations, the minimum needed to call the tool is present. However, with no output schema, the description is the only place to say what the IPv6 config response looks like or how failures surface, and it says neither.
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 both apMac (with pattern, example format, and a pointer to listDevices) and siteId (default from OMADA_SITE_ID, pointer to listSites) are fully documented structurally. The description adds only the phrase "specific access point" and says nothing about site targeting, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Get IPv6 configuration for a specific access point" gives a specific verb (Get), a specific resource (IPv6 configuration), and a scope (per-AP). It is separable from adjacent AP getters such as getApGeneralConfig or getApVlanConfig by resource noun, but it never names those siblings explicitly, so the differentiation is left implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the phrase "for a specific access point" signals that an AP identity is required, and the schema's apMac description carries the routing hint (use listDevices). The description itself states no when-to-use condition, no prerequisites (e.g. IPv6 must be enabled on the AP/site), and no alternatives to prefer for general or VLAN config.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApLldpConfigBRead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing the return payload ('enabled state and advertised TLVs'), but says nothing about auth requirements, default-site behavior when siteId is omitted, or error cases for an unknown AP.
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 purpose and return values are front-loaded in the first two sentences, which is good. The trailing sentence explaining what LLDP is generally is educational filler that does not help an agent select or invoke this tool, so it does not earn 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?
For a simple two-parameter read tool with full schema coverage, annotations, and no output schema, the description is nearly sufficient — it even describes the return shape in lieu of an output schema. Only the default-site fallback and failure behavior are left implicit, and the schema covers the former.
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 apMac format and siteId defaulting behavior fully documented in the schema, so the baseline is 3. The description adds no parameter-level meaning beyond the schema, such as what happens if the AP has LLDP disabled.
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?
States a specific verb and resource ('Get LLDP configuration for an access point') and even names the return contents, so it is clearly separable from siblings like getApSnmpConfig or getApGeneralConfig. It stops short of explicitly contrasting itself with those siblings, which keeps it at 4 rather than 5.
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?
There is no explicit when-to-use or when-not-to-use guidance, and no mention of prerequisites such as needing a known AP MAC. Usage is only implied by the name and by being an AP-scoped read of one specific config area.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getAppControlCategoriesARead-only
Get application control categories (families) for a site, listing available app category definitions used in application control rules.
| 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. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that results are scoped per-site; it says nothing about whether the list is paginated, whether it can be large, or how the default site fallback behaves at runtime, leaving little beyond structured data.
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?
A single front-loaded sentence with no filler and no repetition. It is efficient, though the parenthetical '(families)' plus the trailing clause makes it slightly denser than necessary for the amount of information conveyed.
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-only, single-optional-parameter lookup with no output schema, the definition gives enough to call the tool correctly and understand what comes back conceptually (category definitions). Slightly more detail on result shape would make it complete, but nothing essential is missing.
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 siteId property already documents targeting, the OMADA_SITE_ID default, and the listSites discovery hint. The description's 'for a site' merely echoes that, adding no new syntax, format, or behavioral detail about the 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?
States a specific verb and resource ('Get application control categories (families) for a site') and clarifies what the objects are ('app category definitions used in application control rules'). This separates it from the rules-listing sibling getAppControlRules without naming that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer it is a prerequisite/reference lookup for app control rule configuration. The description never says when to call this versus getAppControlRules or getApplicationControlStatus, and offers no prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getAppControlRulesARead-only
Get application control rules for a site, listing application-level firewall rules that allow or block specific apps or app categories.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of results per page (1–1000). |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful domain context that these are application-level firewall rules with allow/block semantics, but says nothing about pagination behavior or the shape of the returned rule set.
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 front-loaded sentence with the resource named first and its meaning appended as a clause; there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a list-style response, the description could say more about what a rule object contains or how pagination totals are returned. For a simple, read-only, fully documented-schema list tool it is adequate but thin on return-value context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the page, pageSize, and siteId semantics (including the OMADA_SITE_ID fallback and listSites hint) are already fully documented in the schema. The description adds no parameter meaning beyond that, which is the expected baseline at full 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 states a specific verb and resource ('Get application control rules for a site') and explains what those rules are: application-level firewall rules that allow or block apps or app categories. This distinguishes it from the closely named siblings getAppControlCategories and getAppControlStatus, though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the resource being listed; there is no explicit statement of when to prefer this tool over getAppControlCategories, getFirewallSetting, or getUrlFilterRules, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApplicationControlStatusBRead-only
Get application control (DPI) status and configuration for a site.
| 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. |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered externally. The description adds that both status and configuration are returned, which is useful context, but says nothing about what the response contains, whether DPI must be enabled first, or any permission requirements.
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 front-loaded sentence that states the resource and scope with no filler. Nothing could be cut without losing meaning.
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 read-only, single-optional-parameter getter with no output schema, the definition covers what the tool returns at a high level (status and configuration) and the schema covers the input fully. It leaves the shape of the returned status/config unspecified, which is a minor gap for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter at 100% schema description coverage, the schema already fully explains siteId, including the default-site fallback and the pointer to listSites. The description's phrase 'for a site' merely echoes that, adding no new semantics, so the baseline 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 gives a specific verb (Get) and resource (application control/DPI status and configuration) scoped to a site, which is enough for an agent to tell it apart from the rules-oriented siblings getAppControlRules and getAppControlCategories. It stops short of explicitly naming those siblings or contrasting scope with them, so it is clear but not maximally differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance, and no mention of the closely related app-control tools in the sibling list. An agent must infer that this is the status/config read while getAppControlRules and getAppControlCategories handle rule and category listings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApQosConfigCRead-only
Get QoS configuration for a specific access point.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that: it does not say what the returned QoS configuration contains, how the default-site fallback behaves, or whether an AP not configured for QoS returns defaults or an error.
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?
One front-loaded sentence with zero filler or redundancy. It is efficient, though its brevity costs it in the other dimensions rather than in structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only getter with full schema coverage and no output schema, the definition is minimally sufficient to invoke correctly. It nonetheless omits what the agent will receive (e.g., which QoS attributes) and how to handle a missing AP or unset QoS policy.
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 both apMac (with pattern and example) and the optional siteId (with default-site fallback) are already well documented. The description contributes no additional parameter meaning, so the baseline 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 states a specific verb ('Get') and resource ('QoS configuration') and scopes it to 'a specific access point', which separates it from gateway-level siblings such as getGatewayQosClassRules and getQosPolicy. It does not, however, name any of those siblings or clarify how AP QoS differs from the broader QoS policy 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?
There is no explicit when-to-use guidance, no prerequisites, and no named alternatives among the many QoS-adjacent siblings (getQosPolicy, getTrafficPriority, getBandwidthCtrlDetail). The only routing hints ('Use listDevices to find AP MACs', 'Use listSites to discover site IDs') live in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApRadiosARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real value by specifying what the response contains, which matters because there is no output schema. It does not address error handling or permission/site-access requirements, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the capability and its payload, followed by the one prerequisite action. Every clause carries information; there is no filler or restatement of the tool name.
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 two-parameter read-only tool with full schema coverage and safety annotations, the definition supplies both the data returned and the prerequisite lookup, which is enough to call it correctly. Only the distinction from near-neighbor AP config tools is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both the apMac hint ("Use listDevices to find AP MACs") and the siteId default behavior are already documented in the schema. The description's listDevices pointer therefore duplicates rather than extends the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description pairs a specific verb (get) and resource (radio status for an access point) with an enumeration of the actual data returned: 2.4GHz/5GHz band config, channel, TX power, channel utilization and per-radio client count. That detail implicitly separates it from config-oriented siblings like getRadiosConfig, though no sibling is ever named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It offers one workflow hint ("Use listDevices to get the apMac"), which helps the caller secure the required parameter, but it never states when to choose this tool over getRadiosConfig, getApDetail, or other AP-level getters. Usage is inferable rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApSnmpConfigARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint/destructiveHint annotations already establish the safety profile, so the bar is lower. The description does add value by disclosing what the response contains (SNMP version, community strings, trap settings, enabled state), which matters since no output schema exists, but it says nothing about permission requirements, behavior when SNMP is unsupported on the AP, or the sensitivity of returned community strings.
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 short sentences, front-loaded with the verb and resource, followed by return contents and then usage. No filler or repetition of the parameter details already in the schema.
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 two-parameter read tool with full annotation coverage, the definition is nearly sufficient: purpose, return contents, and usage context are all present. Residual gaps are minor — error/unavailable behavior and the fact that community strings are sensitive data worth handling carefully are unstated.
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 apMac format and the siteId default/fallback are already fully documented in the schema. The description adds no parameter-level meaning (e.g., no hint about site scoping for APs or cross-site lookup) beyond what is already structured.
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 names a specific verb and resource ('Get SNMP configuration for an access point') and enumerates what the configuration contains. The SNMP subject matter distinguishes it naturally from the many sibling getAp*Config tools (QoS, VLAN, LLDP, general), though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'Useful for auditing SNMP-based monitoring configurations' gives an implied use case, but there is no explicit when-to-use/when-not guidance and no pointer to an alternative tool. The agent must infer selection from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApUplinkConfigARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A3.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description then adds value by disclosing what the payload contains (uplink mode, preferred uplink settings, failover configuration) and scoping it to a single access point. It stops short of noting any permission, rate-limit, or error behavior, so it is strong but not exhaustive given the lower bar annotations set.
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 short sentences, front-loaded with the verb and resource, then the return contents, then the use case. No filler or repetition, though the second and third sentences could be tightened into one.
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?
There is no output schema, so the description usefully compensates by enumerating the returned fields. Combined with annotation coverage and a fully documented schema, an agent has nearly everything needed; only the sibling disambiguation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (apMac, siteId) are documented in the schema itself, including the format example and pointers to listDevices/listSites. The description adds no further meaning about parameters, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource (get the uplink configuration for an access point) and enumerates the returned facets: uplink mode (wired/wireless mesh), preferred uplink settings, and failover configuration. It does not, however, distinguish this tool from close siblings such as getUplinkWiredDetail or getMeshStatistics, which cover overlapping territory.
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 closing sentence 'Useful for understanding mesh topology and wired uplink assignments' implies a context for use, but there is no explicit when-to-use/when-not-to-use guidance and no named alternatives. An agent facing the many AP and uplink siblings must infer the boundary itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApVlanConfigARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered without description help. The description adds that the response shape includes management VLAN plus per-SSID tagging, which is useful behavioral context, but says nothing about what happens when VLANs are unconfigured, whether settings are inherited from a site profile, or any permission requirements.
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 short sentences, front-loaded with purpose followed by return contents and then a usage note. No filler, no restatement of the tool name, and every sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool, the definition plus annotations plus fully documented schema covers nearly everything an agent needs, and the description even compensates for the missing output schema by naming the returned fields. The only shortfall is the absence of failure-mode or fallback behavior when VLAN data is absent.
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%: apMac's format, an example, and the pointer to listDevices, plus siteId's default-from-OMADA_SITE_ID fallback and the listSites pointer, are all documented in the schema. The description adds no parameter-level meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Get VLAN configuration for an access point') and enumerates what is returned ('management VLAN and per-SSID VLAN tagging settings'), which cleanly separates it from sibling config readers like getApUplinkConfig, getApGeneralConfig, or getApQosConfig. It does not name any sibling explicitly, so differentiation is implied by domain rather than stated.
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 clause 'Useful for verifying network segmentation on wireless infrastructure' gives a concrete use context, which is better than nothing. However, there is no when-not guidance, no mention of adjacent tools (e.g. use getApGeneralConfig for broader AP settings), and no prerequisites such as the AP needing to be online or the site needing to be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getAttackDefenseSettingBRead-only
Get the DDoS and attack defense configuration, including flood protection settings and thresholds.
| 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. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered structurally. The description contributes a small amount beyond that by scoping what the read returns (flood protection settings and thresholds), but says nothing about whether defaults are materialized, whether the response is site-scoped, or how large it may be.
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?
One sentence, front-loaded with the verb and resource, with no filler or redundancy. It is appropriately sized for a single-parameter read tool, though it is brief enough that a little more routing or scope detail could have been added without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, zero-required-parameter read with full schema coverage and safety annotations, the description covers the essentials. It stops short of describing the shape of the returned configuration beyond two example categories, and there is no output schema to fill that 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% and the single siteId parameter is already documented in the schema, including its regex pattern, the OMADA_SITE_ID fallback, and the pointer to listSites. The description adds nothing further about the parameter, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Get the DDoS and attack defense configuration') and enumerates the payload ('flood protection settings and thresholds'), which clearly separates it from the many adjacent *Setting/get* siblings such as getFirewallSetting or getDot1xConfig. It does not explicitly name when to prefer it over those neighbors, but the resource naming is precise enough for an agent to pick it out.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance and no mention of alternatives or prerequisites. An agent must infer the context (auditing DDoS posture for a site) purely from the noun phrase, with no exclusions against firewall/ACL tools that sound similar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getBandwidthCtrlDetailARead-only
Get gateway bandwidth control detail settings for a site, including per-IP and per-SSID bandwidth limits.
| 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. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a little value by saying which configuration sub-areas are returned, but says nothing about behavior when bandwidth control is unconfigured, what happens with the default site fallback, or the response shape.
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?
A single well-formed sentence with the resource and contents front-loaded and no filler. It is efficient, though it could have used the remaining space for a usage cue instead of stopping at the payload list.
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 zero-required-parameter, single-parameter read-only getter with no output schema, the description covers purpose and returned content adequately. The only real omission is guidance on how this differs from the sibling gateway configuration getters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter and 100% schema description coverage, the schema already documents siteId fully, including the OMADA_SITE_ID fallback and the pointer to listSites. The description only restates that the lookup is site-scoped, adding no syntax or format detail 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?
States a specific verb and resource ("Get gateway bandwidth control detail settings") plus the scope ("for a site") and the payload contents ("per-IP and per-SSID bandwidth limits"). It is clearly distinguishable from the many other gateway getters, though it never names a sibling it contrasts with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the agent can infer it reads existing bandwidth-control configuration, but there is no statement of when to choose it over e.g. getGatewayQosClassRules or getSitesGatewaysGeneralConfig, and no mention of prerequisites or when the settings may be empty.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getCableTestFullResultsARead-only
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.
| 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description earns credit for disclosing the payload — per-port cable status (OK/open/short), estimated length, and fault location. It does not say whether results are live-measured or cached from a prior test run, nor whether the call is expensive on large switches, which would be the remaining useful detail.
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 short sentences, front-loaded with the purpose, then the return content, then the sibling comparison — exactly the right ordering. No filler, no restating of the tool name.
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?
With no output schema, the description compensates by describing the returned diagnostic fields, and the two parameters are fully documented in the schema. Together this is sufficient for an agent to decide and call correctly, especially for a read-only tool whose safety profile is already in the annotations.
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%, with both siteId and switchMac fully documented in-schema including patterns and discovery hints (listSites, listDevices), so the baseline is 3. The phrase 'on a switch' and 'all ports' reinforces that switchMac is the required scope selector and that no per-port filtering exists, which adds a small amount of 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 opens with a specific verb and resource — retrieve full cable test results for all ports on a switch — and immediately differentiates itself from the sibling getCableTestLogs by noting it is 'more detailed.' An agent can pick between the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear selection signal against the closest sibling ('More detailed than getCableTestLogs'), implying this is the choice when per-port diagnostics are needed. It stops short of an explicit when-to-use / when-not statement or naming prerequisites, but the practical routing guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getCableTestLogsARead-only
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.
| 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by describing what the payload contains (per-port results, length estimates, fault detection), but says nothing about how much history is returned, retention window, or whether results can be stale.
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 short sentences, front-loaded with the purpose, followed by return content and one usage note. No filler, though the third sentence is generic enough that it borders on boilerplate.
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, so the description must convey the return shape, and it does so at a useful level of abstraction. With only two fully documented parameters this is close to sufficient; the missing piece is how to interpret or bound the returned history.
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%: siteId explains the default-site fallback and points to listSites, and switchMac documents the MAC format and points to listDevices. The description adds only that logs are per-switch, which does reinforce why switchMac is required, but contributes little 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?
States a specific verb and resource ("Get cable test logs for a switch") and enumerates the returned content (per-port results, cable length estimates, fault detection). It is clear on its own, but it never distinguishes itself from very close siblings such as getCableTestFullResults or listSitesCableTestSwitchesPorts, leaving the agent to guess which cable-test tool to call.
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?
"Useful for diagnosing physical layer connectivity issues" gives a context-of-use signal, which is more than nothing. However, there is no explicit when-to-use versus the several other cable-diagnostic siblings and no stated preconditions (e.g. whether the switch must support cable diagnostics or a prior test must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getClientDetailARead-only
Get full detail for a specific client by MAC address, including connection info, IP, VLAN, signal strength, and traffic stats.
| 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. | |
| clientMac | Yes | MAC address of the client to retrieve details for. |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a read-only, non-destructive operation, so the safety profile is covered. The description adds valuable context by enumerating what the response contains (connection info, IP, VLAN, signal strength, traffic stats), which matters since there is no output schema; it stops short of stating what happens when the MAC is unknown or the client is offline.
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 front-loaded sentence with the resource, the identifying key, and the payload summary in that order. No filler 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?
For a two-parameter, read-only lookup with no output schema, the description supplies the essential return-value summary and the lookup key. It omits error/empty-result behavior and the site scoping default, which are minor given the small surface area.
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 both parameters are already fully documented in the schema, and the description only restates the MAC-address lookup key. It says nothing about the optional siteId or the default-site fallback, so it adds no meaning beyond structured data.
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?
Uses a specific verb ('Get full detail') and resource ('a specific client'), and identifies the lookup key (MAC address) plus the categories of data returned. This separates it implicitly from the list- and diagnose-oriented siblings, but no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: fetch a single client's detail when you already know its MAC. There is no explicit when-to-use/when-not, no pointer to listClients/getGridKnownClients for discovering a MAC, and no guidance on preferring diagnoseClient for troubleshooting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getClientsDistributionARead-only
Get client count distribution by connection type and band (wired, 2.4GHz, 5GHz, 6GHz). Useful for understanding the network composition at a glance.
| 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. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered without the description's help. The description adds that results are aggregated by connection type and band, but says nothing about whether counts are real-time or cached, whether disconnected clients are included, or what the response shape looks like. With annotations carrying the safety burden, this is a reasonable but not rich disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core capability front-loaded and the enumerated bands immediately defining scope. The second sentence is lightly promotional ('at a glance') but still conveys intent, so little is wasted.
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?
This is a simple read-only aggregate with a single optional parameter and no output schema, and the description states the dimensions of the aggregation, which is the main thing an agent needs. Nothing critical is missing, though a note on whether the metric is site-wide only would close the last 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 description coverage is 100%, and the siteId property already explains the default-site fallback and points to listSites for discovery. The description adds no parameter meaning beyond that, so the baseline 3 applies: the schema does the work, the description neither helps nor hurts.
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 names a specific verb and resource (client count distribution) and enumerates the exact buckets returned (wired, 2.4GHz, 5GHz, 6GHz), so an agent knows precisely what data comes back. It stops short of distinguishing itself from near-neighbours such as getTrafficDistribution or getDashboardWifiSummary, which is the only thing separating it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the phrase 'useful for understanding the network composition at a glance'. There is no explicit when-to-use condition, no when-not to use it, and no pointer to a sibling tool for related questions. Adequate but leaves the agent to infer the selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardMostActiveEapsARead-only
Get the most active access points (EAPs) in a site, sorted by traffic volume.
| 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. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered and the description's added value is the traffic-volume sort order. However, it never states the measurement window for 'traffic volume' or how many EAPs are returned, which are the key behavioral facts an agent needs to interpret the output.
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 front-loaded sentence with zero filler that states the resource, the scope, and the ordering in one pass.
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 one-parameter read-only dashboard tool with no output schema, the definition is nearly sufficient, especially with a fully documented parameter. The remaining gap is that 'traffic volume' is undefined in time window or result count, which affects how an agent reports the data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the sole siteId parameter is fully documented in the schema, including the OMADA_SITE_ID default fallback and the listSites discovery hint. The description only restates the site scoping at a high level and adds no syntax or format meaning 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 pairs a specific verb (Get) with a specific resource (most active access points / EAPs) and adds the ranking criterion (sorted by traffic volume) plus the site scope. It is easily separable from getDashboardMostActiveSwitches and listMostActiveClients by resource type, though neither sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the 'most active' framing; there is no statement of when to pick this over getDashboardMostActiveSwitches, getDashboardTrafficActivities, or listMostActiveClients, and no prerequisites are mentioned. The schema's siteId description does route discovery to listSites, which partially compensates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardMostActiveSwitchesBRead-only
Get the most active switches in a site, sorted by traffic volume.
| 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. |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the sort criterion (traffic volume), but omits how many switches are returned, whether a top-N cap applies, and what time window 'most active' covers — meaningful gaps for a ranking 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?
A single well-formed sentence with the resource and the sort criterion front-loaded and no filler. Nothing could be removed without losing meaning.
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?
This is a simple read with one optional parameter, so low complexity keeps the bar modest. However, with no output schema, the description should say what a returned entry looks like (switch identity plus traffic figures) and how the ranking is bounded; neither is present.
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%: siteId already documents the pattern, the OMADA_SITE_ID default fallback, and the listSites discovery path. The description adds nothing beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Get') plus resource ('most active switches') and adds the ordering criterion ('sorted by traffic volume'). It implicitly distinguishes itself from getDashboardMostActiveEaps and getDashboardSwitchSummary by resource and metric, though it never names those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use context, no exclusions, and no pointer to alternatives such as getDashboardSwitchSummary or listDevices. The only usage hint is the word 'Dashboard' in the name, which the description does not reinforce.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardOverviewARead-only
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.
| 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. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered by structured data. The description's main addition is the return payload contents, which is useful since no output schema exists. It does not disclose whether counts are live or cached, how large the connectivity graph is, or whether it is expensive/slow to call — behavioral details that would help an agent decide placement in a call sequence.
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 filler. The substantive content (what the overview contains) comes first, with the usage hint trailing. Nothing is redundant with the title or annotations.
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 no output schema and a single optional parameter, the description carries the burden of telling the agent what comes back, and it does so concretely across four categories. The only shortfall is that it doesn't frame itself relative to the dense cluster of sibling dashboard and health tools, which is the main ambiguity an agent faces here.
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% — the siteId field already documents its pattern, the OMADA_SITE_ID default fallback, and the pointer to listSites. The description adds nothing about parameters, which is acceptable given full schema coverage but earns only 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?
Uses a specific verb ('Get') plus a concrete resource ('site overview topology') and then enumerates exactly what is included: device counts by type, client counts by type, connectivity graph, health status. That enumeration distinguishes it from narrow siblings like getDashboardWifiSummary or getDashboardSwitchSummary. It stops short of naming those siblings explicitly, so it's clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The sentence 'Good first call to understand what's in the network' gives a genuine usage cue (entry point / orientation), which is better than nothing. However, it never states when NOT to use it, nor does it route to the many sibling dashboard summaries (getNetworkHealthSummary, getDashboardTrafficActivities, getDashboardPoEUsage) for deeper drill-down. An agent must infer the boundary from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardPoEUsageARead-only
Get PoE (Power over Ethernet) usage statistics for a site, showing power consumption per switch.
| 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. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds the aggregation model (per-switch power consumption for a whole site), which is useful context beyond the annotations, but says nothing about return shape, time window, or what happens when no PoE devices exist.
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 front-loaded sentence with the resource name first and the reporting granularity second; there is no filler, hedging, or redundant restatement of the title.
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 read-only, no-required-parameter tool with a fully documented single parameter and no output schema, the description covers purpose and granularity adequately. Minor gaps remain around the reporting window (real-time vs. historical) and whether results are per-port or per-switch only.
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 single optional siteId parameter already documents the pattern, the OMADA_SITE_ID default fallback, and the listSites discovery hint. The description adds no parameter detail, which is acceptable given the schema does the work, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Get') and resource ('PoE usage statistics for a site') and adds the unit of reporting ('power consumption per switch'), so an agent knows exactly what data comes back. It does not, however, distinguish itself from nearby dashboard siblings such as getDashboardSwitchSummary or getDashboardMostActiveSwitches, which likely also cover switch-level power or activity.
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 scope 'for a site' implicitly tells the agent this is the tool for site-wide PoE power checks, but there is no explicit when-to-use statement, no exclusions, and no mention of how it differs from the many other getDashboard* tools. Usage is inferable from the purpose rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardSwitchSummaryARead-only
Get switch summary for a site dashboard: total switch count, total ports, active ports, PoE budget used vs available, and aggregate bandwidth.
| 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. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the bar is lower. The description adds that the result is an aggregate summary (counts and totals rather than per-switch records), which helps set expectations. It says nothing about freshness, caching, or whether totals include offline switches — meaningful for a dashboard metric 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?
A single front-loaded sentence with the action first and the returned metrics enumerated after a colon. Every clause earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by listing the aggregate fields the caller will receive, and the one optional parameter is fully handled by the schema. Minor omission: it doesn't say whether figures are site-wide for all switches or filtered, but for a low-parameter read-only dashboard tool this is nearly 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% and the single siteId parameter is fully documented in the schema, including the OMADA_SITE_ID default and the listSites discovery hint. The description adds no parameter meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb ('Get') and resource ('switch summary for a site dashboard') and enumerates the exact metrics returned: switch count, ports, active ports, PoE budget, bandwidth. That makes its role distinguishable from granular siblings like getDashboardPoEUsage or getSwitchDetail. It stops short of explicitly contrasting itself with the other dashboard tools (getDashboardOverview, 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?
Usage is only implied by the words 'for a site dashboard' — an agent can infer this is an at-a-glance aggregate rather than a per-device query. There is no explicit statement of when to prefer this over getDashboardOverview or getSitesSwitchesEs, and no preconditions or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardTopCpuUsageBRead-only
Get the top devices by CPU usage for a site, useful for identifying overloaded devices.
| 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. |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description adds that results are ranked 'top' devices, but does not disclose how many devices are returned, the ranking direction, or the sampling time window – meaningful gaps for a dashboard metric tool even with annotations present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the resource and scope first, followed by the use case. No wasted wording, though it is brief enough that a few more specifics could have been added without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and full schema documentation, the description covers purpose adequately. However, with no output schema present, it does not describe the shape of the response (device list with CPU percentages, sort order, result count), which an agent would need to interpret results.
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 siteId property already documents its pattern, default fallback to OMADA_SITE_ID, and the listSites discovery path. The description only echoes 'for a site', adding no semantics beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get the top devices by CPU usage') plus a scope ('for a site'), which is clearly distinguishable from the sibling getDashboardTopMemoryUsage. It stops short of explicitly naming that sibling as the alternative to use for memory metrics, so it is clear but not fully differentiated in text.
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?
'Useful for identifying overloaded devices' implies the operating context (capacity troubleshooting) but gives no explicit when-to-use vs. when-not, and names no alternative such as getDashboardOverview or getDashboardTopMemoryUsage. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardTopMemoryUsageBRead-only
Get the top devices by memory usage for a site, useful for identifying memory-constrained devices.
| 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. |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only a use-case rationale and does not disclose how many devices constitute 'top', the ranking direction, or what the response looks like — meaningful gaps for a 'top-N' style tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence with the resource front-loaded and the rationale trailing; nothing is redundant. It could be slightly sharper by folding the use case into the first clause but it wastes no 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 tool is simple (one optional, fully documented parameter, read-only), so most requirements are met. However, with no output schema, the description should say what 'top devices by memory usage' actually returns (device list with memory percentages? a count?) and how many, which it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the siteId parameter already documents the OMADA_SITE_ID default and points to listSites. The description adds nothing beyond the schema, so the baseline 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?
States a specific verb and resource: 'Get the top devices by memory usage for a site.' An agent can distinguish it from the sibling getDashboardTopCpuUsage by the 'memory' qualifier, though the description never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'useful for identifying memory-constrained devices' implies a use case (troubleshooting devices near memory limits), but there is no explicit when-to-use vs when-not guidance and no pointer to the CPU or PoE dashboard siblings as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardTrafficActivitiesARead-only
Get traffic activity time-series data for a site, showing upload and download trends over time.
| 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. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Read-only, non-destructive behavior is already fully declared by annotations, so the description only needs to add context. It adds the notable fact that results are time-series with upload and download series, but omits the time window, granularity, and whether the range is fixed server-side — material for a trend query with no time parameters.
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 front-loaded sentence with a clear verb, resource, and scope; every clause (time-series, upload/download, over time) contributes information and there is no 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?
With one optional parameter, no nested objects, and no output schema, the description conveys the essential purpose and the shape of the returned data (upload/download trends over time). The main remaining gap is the absence of any statement about the time range or sampling interval, which an agent cannot infer from the parameter list.
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 siteId is already documented there, including the config default and listSites discovery. The description's 'for a site' adds nothing beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (get traffic activity time-series for a site) and names the measured content (upload/download trends), which separates it from dashboard siblings like getDashboardOverview or getTrafficDistribution. It stops short of explicitly contrasting those siblings, so it is clear but not maximally differentiated.
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 phrase 'traffic activity time-series' implies usage for trend inspection, but the description never says when to prefer this over getTrafficDistribution or getDashboardOverview, nor any prerequisites. The site defaulting behavior and listSites discovery hint live only in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardWifiSummaryARead-only
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.
| 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. |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered and the description doesn't need to repeat it. What the description does add beyond the annotations is the payload contract: the specific metrics an agent will get back, which is genuinely useful since there is no output schema. It stops short of saying whether counts are aggregate or time-windowed.
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 front-loaded sentence that states the resource first and then the metric list. No filler, no redundancy, and the enumerated metrics are compact rather than sprawling.
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 single-optional-parameter read tool with read-only annotations and no output schema, the description plus schema supply nearly everything needed to call it correctly. The one remaining gap is scope: it doesn't say whether the summary reflects real-time state or a default time window, which matters for interpreting the numbers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains siteId, its pattern, the OMADA_SITE_ID default fallback, and the pointer to listSites. The description mentions nothing about the parameter, so it adds no meaning here – the baseline 3 applies because the schema does all the work.
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 gives a specific verb and resource ("Get WiFi summary for a site dashboard") and enumerates the exact metrics returned (AP totals, client count, channel utilization per band, SSID count). It does not distinguish itself from closely related siblings like getDashboardOverview or getApDetail, so an agent still has to infer which dashboard summary to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the word "dashboard" – the agent can infer this is a high-level rollup rather than per-device detail, but there is no explicit statement of when to prefer it over getApDetail or getDashboardOverview, and no mention of the default-site behavior when siteId is omitted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDeviceTagListCRead-only
Get the list of device tags defined in a site.
| 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. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered, but the description adds nothing beyond them. There is no mention of whether tags are site-scoped only, whether an empty list is returned when none are defined, whether results are paginated, or what a tag record contains.
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?
One short sentence with no wasted words and the key scope qualifier front-loaded. It is efficient but so brief that it carries no structuring benefit beyond the surface statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-output-schema read of one optional parameter, the description is minimally sufficient to invoke correctly. It leaves open the return shape and the default-site behavior, though the latter is at least recoverable from 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% and the single siteId parameter is fully documented in the schema, including the OMADA_SITE_ID default and the pointer to listSites. The description adds no meaning beyond that, so the baseline 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?
States a specific verb (get), resource (device tags), and scope (defined in a site), so an agent knows exactly what is returned. It does not differentiate itself from any of the many sibling tag/device/config listers in the namespace.
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 when-to-use context, no prerequisites, and no alternatives named. The description does not say to use this only when tags are the object of interest versus, say, listDevices or getAllDeviceBySite, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDot1xConfigBRead-only
Get the 802.1X (dot1x) authentication configuration for a site, including enabled state, authentication mode, and RADIUS server settings.
| 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. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds real value by naming the returned fields (enabled state, mode, RADIUS server settings), but says nothing about scoping behavior, error cases when dot1x is unconfigured, or fallback to the default site.
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?
One front-loaded sentence that puts the resource before the return payload, with zero filler. It is appropriately sized for a simple read tool, though it could have used the remaining space to route against the sibling tool.
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 read-only getter with one optional parameter, no output schema, and no nesting, the description covers the essentials and even previews the response shape. The main missing piece is disambiguation from getSwitchDot1xSetting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single optional siteId parameter is fully documented there, including the OMADA_SITE_ID default and the listSites discovery path. The description adds no parameter meaning beyond the schema, so the baseline 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?
States a specific verb ('Get') plus the exact resource ('802.1X (dot1x) authentication configuration for a site') and enumerates what is included (enabled state, authentication mode, RADIUS server settings). This is clear, but it never distinguishes itself from the sibling tool getSwitchDot1xSetting, so an agent cannot resolve the near-duplicate dot1x getters from the description alone.
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 offers no when-to-use guidance, no exclusions, and no mention of the sibling getSwitchDot1xSetting that appears to cover overlapping ground. The only usage hint in the whole definition lives in the input schema (listSites for discovering site IDs), not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDownlinkWiredDevicesARead-only
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).
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-destructive read, so the safety profile is covered. The description adds that the result is a device list containing MAC addresses and connection details, but says nothing about empty results, pagination, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences: what it returns, how the devices are connected, and when it is relevant. The purpose is front-loaded and nothing is redundant.
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 two-parameter read with no output schema, the description covers purpose, return content, and applicability. The phrase 'connection details' remains vague about the actual fields returned, which is the only real 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 description coverage is 100%; apMac format and the siteId default/fallback are fully documented in the schema, including pointers to listDevices and listSites. The description adds no parameter meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: get wired downlink devices on an AP's LAN port. The word 'downlink' plus 'using the AP as a wired switch' clearly separates this from uplink-oriented siblings such as getUplinkWiredDetail and from general device lists like listDevices.
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?
Gives a usable context: 'Useful for APs with built-in switch ports (e.g. EAP615-Wall)', which tells the agent when this applies. It stops short of naming alternatives or stating when not to use it (e.g. for wireless clients or uplink ports).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getFirewallSettingBRead-only
Get the site-global firewall settings returned by the official Omada firewall endpoint.
| 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. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a safe read-only operation, so the description does not need to repeat that. It adds the useful scope detail that the settings are site-global, but 'returned by the official Omada firewall endpoint' is implementation provenance rather than additional behavioral context such as return shape or fallback behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no unnecessary elaboration. The trailing 'returned by the official Omada firewall endpoint' phrase is mildly redundant and adds little agent-facing value, but overall it remains concise.
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-only tool with one optional, fully documented parameter and annotations covering safety, the definition is largely complete. The lack of any return-value explanation is a minor gap because there is no output schema, but the operation is straightforward enough that an agent can still call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the siteId parameter is already fully documented in the schema, including the default-site fallback and the listSites discovery hint. The description adds no parameter-level meaning beyond the schema, so the baseline 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 gives a specific verb ('Get') and resource ('site-global firewall settings'), making the operation understandable without opening the schema. It does not explicitly distinguish this general firewall-settings read from the many sibling firewall/ACL/filter configuration 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?
There is no guidance on when to use this tool versus alternatives such as ACL, URL filter, attack-defense, or QoS configuration tools. The only contextual clue is the 'site-global' scope, which is useful but does not amount to usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getFirmwareInfoARead-only
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.
| 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. | |
| deviceMac | Yes | MAC address of the device (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find device MACs. |
TDQS
A3.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying the exact return payload (current version, latest version, upgrade availability) in the absence of an output schema. It stops short of mentioning pagination, freshness of the 'latest' data source, or error behavior for unknown MACs.
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 short sentences, front-loaded with the action and return values, then the prerequisite hint. The only redundancy is the listDevices pointer, which duplicates the deviceMac schema description.
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 two-parameter read-only tool with no output schema, the description adequately covers purpose, return contents, and how to source the required MAC. The remaining gap is sibling differentiation within the crowded firmware/upgrade tool family, which matters given several similarly named neighbors.
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 deviceMac documented including format and discovery hints. The description's 'use listDevices to get deviceMac values' merely restates what the schema already says, adding no new syntactic or semantic detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource (get firmware info for a device) and enumerates the three returned values, so the agent knows exactly what the tool produces. It is clear but does not distinguish itself from firmware-adjacent siblings such as getFirmwareUpgradePlan 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description points the agent to listDevices to obtain deviceMac, which is a concrete prerequisite. However, it gives no guidance on when to use this per-device tool versus getFirmwareUpgradePlan or the listUpgrade* siblings, so sibling selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getFirmwareUpgradePlanCRead-only
Get the firmware upgrade plan list for devices managed by the controller.
| Name | Required | Description | Default |
|---|---|---|---|
| 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. Beyond that the description only adds the scope phrase 'devices managed by the controller'; it says nothing about pagination defaults, whether results are per-device or per-plan, ordering, or result-set size, which matter for a paginated list endpoint.
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?
A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity comes at the cost of specification rather than because everything necessary has been said.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only list tool with no complex schema or nested objects, the entry is adequate. But with no output schema, the description should have clarified what a 'firmware upgrade plan' entry looks like (per-device plan status, target firmware, schedule), which it leaves entirely implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (page, pageSize) carry their own bounds and defaults, so the schema does the heavy lifting. The description adds no meaning beyond it, which matches the baseline 3 for a fully documented 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?
Specific verb plus resource: 'Get the firmware upgrade plan list' scoped to 'devices managed by the controller'. However, it does not differentiate from nearby siblings such as getFirmwareInfo, listUpgradeFirmwares, getUpgradeLogs, or getGridAutoCheckUpgrade, so an agent still has to guess which upgrade-related endpoint returns plans versus firmware catalog entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance and no exclusions. With four-plus firmware/upgrade siblings in the toolset, the description gives the agent nothing to disambiguate plan retrieval from firmware listing, upgrade logs, or auto-check-upgrade settings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGatewayDetailARead-only
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.
| 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. | |
| 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
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a non-destructive read, so the description's job is to add context — and it does, by spelling out the configuration facets returned even though no output schema exists. It does not mention failure behavior for an unknown/incorrect MAC or permission scope, but that is a minor omission against the annotation coverage.
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 what is fetched and the enumerated payload, followed by a single prerequisite pointer. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only lookup with no output schema, the description gives enough — it lists the returned facets and the MAC-sourcing prerequisite, while the schema covers site defaults. It falls just short of complete because it does not delimit the tool against the other gateway detail endpoints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented there, including the same listDevices hint and the default-site fallback. The description repeats the listDevices guidance rather than adding new meaning, so the baseline 3 is the right level.
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?
Uses a specific verb ("Fetch") plus resource ("gateway") and enumerates the returned facets — model, firmware, CPU/memory, WAN/LAN ports, routing mode, feature flags — so an agent knows exactly what the call yields. It is implicitly distinguished from siblings like getSwitchDetail/getApDetail by the gateway scope, but it does not say how it differs from the other gateway-specific tools (getGatewayWanStatus, getGatewayLanStatus, getSitesGatewaysGeneralConfig).
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?
"Use listDevices to get the gatewayMac" supplies a concrete prerequisite, which is real usage guidance. However, it never states when to choose this tool over the closely named gateway siblings, nor whether it is safe/appropriate to call in bulk or for a device that is not a gateway.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGatewayHealthARead-only
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.
| 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. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real operational context beyond that — it discloses hidden discovery work ('auto-discovers the site gateway') and that supplying gatewayMac skips it. It does not say what happens when a site has no gateway or multiple gateways, nor how expensive the discovery listing is, but the composite nature and the discovery shortcut are meaningfully surfaced.
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 the composite payload and its three components, then the diagnostic use cases, then the optimization hint. Every clause carries information an agent would act on; nothing is padding or restatement of the tool name.
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 no output schema, the description compensates by enumerating the returned fields (CPU, memory, firmware, ports, WAN link state/IP/ISP, LAN statuses), which is enough for an agent to know what it will get back. The only gap is failure behavior — no mention of the outcome when discovery finds no gateway or when siteId is invalid.
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 both siteId and gatewayMac are already documented, including the default-site fallback and the auto-discovery behavior. The description's 'Optionally accepts a gatewayMac to skip discovery' largely restates the schema; it adds the framing of discovery as a cost to avoid but no new syntax or constraint details. Baseline 3 for a fully covered 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?
States a specific verb and resource ('Composite gateway health check') and immediately enumerates the three data classes bundled: gateway detail (CPU, memory, firmware, ports), WAN port statuses, and LAN interface statuses. The word 'composite' distinguishes it from the granular siblings getGatewayDetail, getGatewayWanStatus, and getGatewayLanStatus without the agent needing to open any schema.
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?
Gives explicit triggering conditions: 'diagnosing internet connectivity issues, WAN failover, or gateway performance problems.' That is solid when-to-use coverage. It stops short of naming the granular alternatives (getGatewayWanStatus, getGatewayLanStatus) as the choice for narrow single-aspect queries, leaving that inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGatewayLanStatusARead-only
Get LAN port status for a specific gateway: port link state, speed, duplex, connected device, and VLAN assignment. Use listDevices to get the gatewayMac.
| 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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description correctly stays consistent with that. It adds the returned field set, which is useful given there is no output schema, but says nothing about permissions, caching/freshness, or what an empty or offline port list looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the resource and its returned fields, followed by the one actionable prerequisite. No filler, though the listDevices hint is redundant with the schema and could have been spent on sibling routing instead.
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 read-only two-parameter tool with full schema coverage, the description is adequate: it names the return payload despite having no output schema, which is the main informational gap the agent would otherwise face. Missing is only clearer separation from getGatewayPorts/WAN-status siblings.
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 explains both siteId (default from OMADA_SITE_ID, use listSites) and gatewayMac (with format example). The description's 'Use listDevices to get the gatewayMac' duplicates the gatewayMac property description verbatim in substance, adding no new semantics. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb plus resource ('Get LAN port status for a specific gateway') with an explicit enumeration of what is returned: link state, speed, duplex, connected device, VLAN assignment. The word 'LAN' implicitly separates it from getGatewayWanStatus, but the description never names getGatewayPorts, which is the closest overlapping sibling, so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is a prerequisite: 'Use listDevices to get the gatewayMac.' There is no statement of when to prefer this over getGatewayPorts, getGatewayWanStatus, or getUplinkWiredDetail, and no indication of failure conditions such as a gateway with no LAN ports. Usage is implied by the LAN-port framing rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGatewayPortsARead-only
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.
| 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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. Beyond that, the description discloses the returned content (link status, speed, IP, bytes in/out, port profile), which matters because there is no output schema. It says nothing about pagination, error behavior for an unknown MAC, or size of the response, which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose and returned fields, then the sibling comparison, then the prerequisite. Every sentence carries distinct information 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?
For a read-only, two-parameter lookup tool, the description plus annotations and a fully described schema cover what an agent needs to invoke it correctly. The only remaining gap is behavioral detail about the response shape beyond the field list, which is minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are fully documented there, including the siteId default and MAC format, so the baseline is 3. The description only repeats the listDevices hint already present in the gatewayMac schema field and adds no new meaning for siteId or the MAC format.
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?
States a specific verb and resource ('Get all WAN and LAN port details') and enumerates exactly what is included: link status, speed, IP address, bytes in/out, and port profile. It also distinguishes itself from the sibling tools getGatewayWanStatus and getGatewayLanStatus, so an agent can separate them without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly positions itself relative to alternatives ('More detailed than getGatewayWanStatus or getGatewayLanStatus'), giving a clear selection signal, and adds a prerequisite routing hint ('Use listDevices to get the gatewayMac'). It does not explicitly say when to prefer the lighter-weight siblings, but the comparative guidance is enough for correct routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGatewayQosClassRulesBRead-only
Get the gateway QoS class rules for a site, including traffic classification rules and DSCP/priority markings.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of results per page (1–1000). |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the payload includes classification rules and DSCP/priority markings, which is modest value beyond the annotations, but it says nothing about pagination of results or the default-site fallback behavior.
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?
A single front-loaded sentence with no filler; the resource identifier comes first and the returned content follows. It is efficient, though it stops short of adding any routing or behavioral detail that would make the length fully earned.
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?
This is a read-only getter with a fully documented three-parameter schema and annotations covering safety, and no output schema, so the description need not describe return values in detail. Its statement of returned content plus the schema's pagination and site defaults make it usable as-is, with only sibling differentiation missing.
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 page, pageSize, and siteId all documented in the schema itself, including the OMADA_SITE_ID fallback and the listSites discovery hint. The description contributes no additional meaning about these parameters, so the baseline 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 names a specific verb and resource ('Get the gateway QoS class rules for a site') and enumerates the content returned (traffic classification rules, DSCP/priority markings), so the agent knows exactly what is fetched. It does not distinguish itself from domain-adjacent siblings such as getQosPolicy, getTrafficPriority, or getAppControlRules, which an agent could easily confuse it with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this rather than getQosPolicy or getTrafficPriority, and no prerequisites or exclusions are given. The only context is implicit in the word 'gateway', leaving the agent to infer selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGatewayWanStatusARead-only
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.
| 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. | |
| 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
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing the shape of the response — per-WAN-port granularity and the specific metrics returned (IP, DNS, uptime, link speed, TX/RX, connection type) — which tells the agent this is a diagnostic snapshot rather than a config read.
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 short sentences with no filler: purpose first, return contents second, parameter resolution third. It is front-loaded and every sentence carries information the agent can act on.
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 no output schema, the description takes on the job of describing returns and does so adequately by listing the returned fields. Minor gaps remain: no note on behavior when the MAC is not a gateway or when a device has no WAN ports, but for a read-only diagnostic tool this is close to 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 both gatewayMac and siteId are already documented in structured form, and the description's 'Use listDevices to find the gatewayMac' largely duplicates the schema text. It adds the per-port scoping notion but says nothing about siteId or the default-site fallback, 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 opens with a specific verb and resource ('Get the WAN port status and connectivity information for a specific gateway') and enumerates exactly what comes back (WAN IP, DNS, uptime, link speed, TX/RX rates, connection type per port). Naming 'WAN port' implicitly separates it from the sibling getGatewayLanStatus, so an agent can pick it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives one concrete prerequisite: use listDevices to resolve gatewayMac, which is useful operational routing. However, it offers no guidance on when to prefer this over getGatewayDetail, getSitesHealthGatewaysWansDetails, or getUplinkWiredDetail, all of which are nearby siblings that could plausibly return overlapping WAN information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridAllowListARead-only
Get the IPS allow list (paginated). Returns entries that are explicitly allowed to bypass IPS inspection. Supports optional keyword search.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| searchKey | No | Optional search keyword to filter IPS allow-list entries. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful domain context that these entries bypass IPS inspection and that results are paginated, but says nothing about ordering, default page contents, or permissions required.
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 short sentences with zero waste; the core identity of the resource is front-loaded, followed by what the entries mean and the one optional filter. Nothing repeats the schema verbatim.
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-only paginated list with full schema coverage and annotations, this is nearly complete. The only soft spot is the absence of any hint about returned entry fields, though no output schema exists to cover that.
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%, including siteId's default-config behavior and the pageSize range, so the schema does the heavy lifting. The description only maps loosely onto searchKey ('optional keyword search') and pagination, adding little beyond what the schema already states.
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?
States a specific verb and resource ('Get the IPS allow list (paginated)') and clarifies the domain meaning of the entries as those explicitly allowed to bypass IPS inspection. It does not name the obvious counterpart sibling getGridBlockList, so an agent must infer the allow-list/block-list split on its own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: it notes optional keyword search and pagination, but never says when to use this versus getGridBlockList or any other grid/ACL listing tool. No prerequisites or exclusions are given, leaving selection to inference from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridAutoCheckUpgradeBRead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered without description help. The description adds that results are a plan/check listing rather than live device state, which is mildly useful, but says nothing about pagination behavior, result volume, or whether the list is grid-wide — notable gaps for a paginated 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and scope, with no redundant phrasing. The trailing 'Useful for...' sentence carries real routing value, though it could have been spent on sibling differentiation instead.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only list tool with full schema coverage and annotations, the description is adequate but thin. It omits pagination semantics and any hint of the return shape (no output schema exists), and it does not clarify the 'Grid' scope implied by the name, which matters given several overlapping upgrade tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (page, pageSize) are documented with defaults and ranges in the schema itself. The description adds no meaning beyond the schema — it does not even mention that results are paged — so the baseline 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 gives a specific verb and resource ('Get the auto-check upgrade plan list') and states the scope ('scheduled firmware upgrade checks across devices'). It is clear what the tool returns, but it never distinguishes itself from closely related siblings such as getFirmwareUpgradePlan or getUpgradeLogs, leaving the agent to guess which upgrade view to pick.
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 second sentence supplies use cases ('auditing upgrade schedules', 'identifying devices due for automatic firmware updates'), which is better than nothing. However, there is no explicit when-not guidance and no reference to the alternative upgrade-plan tools in the sibling set, so selection between them is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridBlockListARead-only
Get the IPS block list (paginated). Returns entries that are explicitly blocked by the Intrusion Prevention System. Supports optional keyword search.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| searchKey | No | Optional search keyword to filter IPS block-list entries. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are paginated and scoped to explicit IPS blocks, but says nothing about ordering, result volume, or whether implicit blocks are excluded from the count.
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 short sentences with the core purpose front-loaded and no filler. The middle sentence partially restates the resource name with extra wording, a small redundancy but not wasteful enough to penalize heavily.
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 read-only paginated list tool with full schema coverage and no output schema, the description covers what is needed to call it correctly. It could note the default-site fallback for siteId, but the schema already documents that.
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 page, pageSize, siteId, and searchKey all documented in the schema itself. The description merely echoes pagination and keyword search at a high level, adding no syntax or matching-behavior detail 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?
States a specific verb ('Get') and resource ('IPS block list'), and clarifies the result set is limited to entries explicitly blocked by the Intrusion Prevention System. That wording implicitly distinguishes it from allow-list siblings such as getGridAllowList, though no sibling is named outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer this is the tool for reviewing blocked IPS entries and that searchKey is optional. There is no explicit guidance on when to prefer this over getGridAllowList or the gateway/EAP rule tools, and no prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridClientHistoryARead-only
Get per-client connection history (paginated). Returns past connection sessions for a specific client including timestamps, SSID/network, traffic, and authentication type.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| clientMac | Yes | MAC address of the client to retrieve history for. | |
| searchKey | No | Search keyword to filter history entries. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false), so the safety profile is covered without description help. The description adds real value by disclosing that results are paginated and what data classes come back, but says nothing about default/maximum page size behavior, empty-result semantics for unknown MACs, or retention window for history.
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 short sentences, front-loaded with the operation and its pagination trait, followed by the return payload. No filler, hedging, or repetition of the tool name.
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 no output schema, the description correctly compensates by naming the returned fields, which is the main thing an agent needs. The remaining gap is disambiguation from the near-identical sibling listClientsPastConnections and any note about how far back history extends.
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 page, pageSize, siteId, clientMac and searchKey all documented in-schema, including defaults, ranges, and the listSites hint for siteId. The description only reinforces 'paginated' and 'specific client', adding no format or syntax detail beyond the schema, so the baseline 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 gives a specific verb and resource ("Get per-client connection history") and enumerates the returned fields (timestamps, SSID/network, traffic, authentication type), which clearly distinguishes it from generic list tools like listClients. However, it never distinguishes itself from the closely named sibling listClientsPastConnections, which an agent could easily confuse with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the required clientMac parameter plus the phrase "for a specific client" signals this is the per-client drill-down, whereas listClients/listClientsPastConnections are broader. There is no explicit statement of when to prefer one over the other, and no mention of prerequisites such as needing a valid MAC from listClients.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridEapRuleARead-only
Get the URL filter AP rules (paginated). Returns URL-based filtering rules applied to wireless clients via access points.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are paginated and the domain of the returned rules, but says nothing about ordering, default page size, or total-count behavior beyond what the schema states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the resource and pagination note front-loaded; no filler. Slightly redundant in that the second sentence largely restates what the first already conveys.
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 read-only, three-parameter paginated list tool with fully documented parameters and no output schema, the description covers what is returned and its scope adequately. The only real gap is routing guidance relative to the many similar URL-filter and ACL siblings.
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 page, pageSize, and siteId fully documented including defaults, ranges, and a pointer to listSites. The description only echoes 'paginated' and adds no meaning beyond the schema, so the baseline 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?
States a specific verb and resource (get URL filter AP rules) and clarifies the scope as rules applied to wireless clients via access points. An agent can distinguish this from generic URL filter tools by the AP/wireless framing, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the phrase 'applied to wireless clients via access points'. No explicit when-to-use, when-not-to-use, or comparison against likely alternatives such as getUrlFilterRules, getUrlFilterBlacklist, or listEapAcls, which appear in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridGatewayRuleBRead-only
Get the URL filter gateway rules (paginated). Returns URL-based filtering rules applied to traffic through the gateway.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are paginated and describes the subject matter of the returned rules, but says nothing about ordering, default scope, or how many rules typically exist beyond what the schema states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler. The second sentence partially restates the first ('URL filter gateway rules' vs 'URL-based filtering rules applied to traffic through the gateway'), but the cost is minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, fully-annotated read tool with complete schema documentation, the definition is adequate but thin. With no output schema present, the description could have sketched the rule fields returned or clarified site scoping, which it leaves entirely to the schema's siteId text.
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 page, pageSize, and siteId all documented in the schema including defaults, ranges, and the listSites discovery hint. The description's only parameter-relevant contribution is the word 'paginated', so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('Get the URL filter gateway rules') and confirms it is paginated, so an agent knows what is being fetched. However, it never distinguishes this from close siblings such as getUrlFilterRules, getGridEapRule, or getGridAllowList/getGridBlockList, leaving the 'Grid/Gateway' naming ambiguous relative to the URL-filter family.
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 when-to-use guidance is offered: there is no statement about which sibling to call for EAP-level rules versus gateway-level rules, nor for allow-list/block-list variants. Usage can only be inferred from the phrase 'applied to traffic through the gateway'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridKnownClientsARead-only
Get historical known clients list (paginated). Returns clients that have previously connected to the site, with optional time range and search filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| guest | No | Filter by guest status ("true" or "false"). | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| timeEnd | No | Filter end time (Unix epoch milliseconds as string). | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| searchKey | No | Search keyword to filter clients by name, MAC, or IP. | |
| timeStart | No | Filter start time (Unix epoch milliseconds as string). | |
| sortLastSeen | No | Sort direction for lastSeen field (e.g. "asc" or "desc"). |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are paginated and filterable by time range and search, but says nothing about default paging behavior, result caps, or response shape beyond the one-line return summary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core identity and pagination front-loaded, and no filler. Slightly more room could have been used to route agents away from overlapping siblings instead of restating the filter set.
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 no output schema, the description does state what the call returns (previously connected clients) and that results are paginated. All eight parameters are documented in the schema, so the main remaining gap is sibling disambiguation rather than missing mechanics.
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% across all eight parameters, including defaults for page and pageSize, ranges, and a siteId note pointing to listSites. The description only restates the time-range and search filters generically, adding no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('Get historical known clients list') and adds scope ('clients that have previously connected to the site'). It does not, however, distinguish itself from close siblings such as listClients, listClientsPastConnections, or getGridClientHistory, which an agent would need to tell apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through 'historical' and 'previously connected', suggesting this is for past/known client retrieval rather than live clients. There is no explicit when-to-use or when-not-to-use guidance, and no baseline alternative (e.g. listClients for current clients) is named despite several overlapping siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getIspLoadARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | End of the time range as a Unix timestamp in seconds (e.g. Math.floor(Date.now() / 1000)). Must be paired with start. | |
| start | Yes | Start of the time range as a Unix timestamp in seconds (e.g. Math.floor(Date.now() / 1000) - 3600 for the last hour). Must be paired with end. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a meaningful behavioral detail — that results are broken out per uplink and include both volume and utilization — but says nothing about retention limits, aggregation granularity, or behavior when a link had no traffic in the window. Consistent with, and additive to, the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences with the core capability front-loaded, followed by the return content and use cases. No filler or repetition. Slight redundancy in restating timestamp units already covered by the schema keeps it from a 5.
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 only three parameters, full schema coverage, and a read-only annotation set, the description supplies what is missing: what the response conceptually contains (per-link volume and utilization). It does not cover retention windows or data granularity, and since there is no output schema, a bit more on the shape of results would 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 description coverage is 100%, and every parameter (start, end, siteId) is documented in the schema, including the siteId fallback to OMADA_SITE_ID and the listSites pointer. The description's note that 'start and end are Unix timestamps in seconds' merely repeats what the schema already states, so it adds no new meaning. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get per-WAN ISP link load over a time range') and clarifies the output subject ('traffic volume and utilization per internet uplink'). An agent can distinguish it from generic WAN-detail tools like getGatewayWanStatus or getUplinkWiredDetail by the 'load/utilization over time' framing, though it never explicitly names or contrasts those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It offers three scenarios ('understanding load balancing behaviour, identifying saturated WAN links, analysing failover events'), which gives implied when-to-use context. However, there is no explicit guidance on when NOT to use it, no mention of alternatives such as getUplinkWiredDetail or getSpeedTestResults, and no stated prerequisites for the time range.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getMacFilterDetailBRead-only
Get the MAC filtering global settings for a site, including whether MAC filtering is enabled and the default action for unmatched clients.
| 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. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the settings are 'global' for a site and names the two values returned, which is useful behavioral context, but it says nothing about pagination, error behavior when MAC filtering is unconfigured, or what other fields come back.
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?
A single sentence that front-loads the resource and then enumerates the returned values, with no filler or redundancy. It could be marginally tighter only by routing to a sibling, not by cutting any existing clause.
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 one-parameter, zero-required, read-only getter with full schema coverage and no output schema, the description supplies enough to call it correctly and to know roughly what comes back. The only meaningful gap is not situating it among the many ACL/allow-list siblings, which matters given how many near-neighbors exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the siteId parameter is documented thoroughly, including the config fallback and a pointer to listSites. The description adds nothing about siteId, so it neither compensates nor detracts; the baseline of 3 applies since the schema does all the work for the single 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 gives a specific verb ('Get') and resource ('MAC filtering global settings') and enumerates the two pieces of information returned (enabled flag, default action for unmatched clients). It is clear what the tool retrieves, though it never names or distinguishes itself from the ACL/allow-list/block-list siblings (getGridAllowList, getOswAclList, getAclConfigTypeSetting), so an agent must infer which MAC-control tool to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no prerequisites, and no mention of the closely related ACL/allow-list tools in the sibling set. The read-only nature is only implied by the word 'Get', leaving the agent to infer that this is a configuration-inspection call rather than a policy-management call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getMeshStatisticsARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A3.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the specific return fields (link quality, signal strength, throughput, hop count) in the absence of an output schema, and by implicitly scoping results to mesh-connected APs — behavior an agent needs to interpret empty or non-applicable results. It does not address what happens for a non-mesh AP or whether results are live vs. cached.
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 short sentences, front-loaded with the action and resource, followed by return fields and usage. Nothing is redundant, though the final sentence is the weakest and could be folded into the first.
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 two-parameter read-only diagnostic tool with no output schema, the description supplies the returned metrics and the mesh-only scope, which is what an agent needs to call and interpret it. The remaining gap — non-mesh AP behavior and error/empty-result handling — is minor given the read-only annotations and fully documented 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%: apMac includes a format pattern plus a pointer to listDevices, and siteId explains the OMADA_SITE_ID default and listSites. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ("Get mesh link statistics for an access point") and enumerates the returned metrics, so the agent knows exactly what it retrieves. It implicitly separates itself from wired/uplink siblings by scoping to "mesh-connected APs," but never names an alternative tool such as getUplinkWiredDetail, keeping it short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Useful for diagnosing mesh network performance" gives a general usage context but no explicit when-to-use vs. when-not, no prerequisites, and no named alternative for wired-link diagnosis. The agent must infer that this only applies to mesh backhaul APs from the return-field list rather than from a stated condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getNetworkHealthSummaryARead-only
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.
| 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. |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: multi-endpoint aggregation in a single call, and that 'individual sections gracefully degrade if an endpoint is unavailable' — important for interpreting partial results. It stops short of describing pagination, response shape, or latency, which keeps it at 4 rather than 5.
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, front-loaded with what the tool is and what it returns, then when to use it, then a caveat about degradation. No filler. Slightly dense section enumeration in sentence one, but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an aggregator with one optional parameter and no output schema, the description covers purpose, recommended call ordering, contents, and failure semantics. What is missing is any signal about result size or that the response is a composite envelope of sections, which would help an agent parse it without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — siteId is fully documented in the schema, including the default-site fallback and the pointer to listSites. The description adds nothing about the parameter, so the 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 states a specific verb and resource ('composite health snapshot — single call') and enumerates exactly what is aggregated: dashboard overview counts, internet/WAN status, client distribution, and active threats. This clearly differentiates it from narrower siblings such as getDashboardOverview or getGatewayHealth, which return only one of those sections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage guidance: 'Use this as the first call when checking if everything is working or when starting any troubleshooting session.' That is a strong positive routing rule, though it never names when to skip it in favor of the individual section tools (e.g., getDashboardOverview or getClientsDistribution) once the agent has drilled into a specific area.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getOsgCustomAclListARead-only
Get the custom gateway ACL rules list (paginated). Custom ACLs extend the standard gateway ACL rules with user-defined traffic policies.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe read operation, so the bar is lower. The description adds the domain context that custom ACLs layer user-defined policies on top of standard gateway ACLs, but says nothing about result ordering, total counts, or behavior when no custom ACLs exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the verb and resource; the second sentence earns its place by defining what a custom ACL is. The '(paginated)' parenthetical is only marginally useful given the schema already exposes paging params.
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?
A read-only, zero-required-parameter list tool with full schema coverage and safety annotations needs little more than this. The definition covers purpose and domain context adequately; only return-shape expectations are unaddressed, which is acceptable without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so page, pageSize, and siteId are fully documented in the schema itself. The description only echoes 'paginated' and adds no syntax, default, or site-targeting detail beyond that 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?
States a specific verb and resource ('Get the custom gateway ACL rules list') and adds a scope qualifier (paginated, custom vs. standard). An agent can tell it apart conceptually from listOsgAcls/getOswAclList, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Custom ACLs extend the standard gateway ACL rules' implies that standard ACL retrieval lives elsewhere, giving implicit routing guidance. However, there is no explicit when-to-use/when-not-to-use statement, no prerequisites, and no named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getOswAclListARead-only
Get the switch ACL list (paginated). Returns per-port or VLAN-based access control rules applied to managed switches.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the result is paginated and describes the nature of the returned rules, which is useful, but it does not cover ordering, total counts, or what an empty result means for a switch with no ACLs.
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 filler, with the resource and pagination stated up front and the returned content clarified immediately after. Nothing repeats the schema or the annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, fully optional-parameter read tool with no output schema, the description gives just enough to know what is returned at a high level, but it omits the shape of the returned rule objects (fields, whether ports/VLAN IDs appear) that an agent would need since no output schema exists.
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%: page, pageSize (with range and default), and siteId (with pattern and a pointer to listSites) are all documented in the schema. The description adds nothing about parameter semantics beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ("Get the switch ACL list") and scopes the content as "per-port or VLAN-based access control rules applied to managed switches," which distinguishes it from the sibling ACL tools for gateways and EAPs (getOsgCustomAclList, listOsgAcls, listEapAcls) without naming them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word "switch" implies this is the tool for switch-side ACLs rather than gateway/EAP ACLs, but no alternative is named and no when-not-to-use condition or prerequisite is stated. Usage is inferable from the scope rather than explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getOswStackLagListARead-only
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.
| 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. | |
| stackId | Yes | Stack ID of the switch stack. Use getSwitchStackDetail to find the stackId. |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by describing the payload shape (configured LAG/trunk groups with member ports, load balancing mode, and status), which is necessary since there is no output schema. It omits edge cases such as behavior when no LAGs are configured or whether disabled/unconfigured groups are included.
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 short sentences, front-loaded with the action and scope, then the return contents, then the prerequisite. No redundant or filler wording; each sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only list tool with no output schema, the definition covers what is returned, the scoping resource, and how to obtain the required ID. Minor gaps remain around empty-result behavior and how siteId affects resolution, but nothing blocks a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both siteId and stackId fully documented in the schema, and the description largely repeats the stackId guidance already present there. It says nothing about siteId or how the default-site fallback interacts with a stackId lookup, so no meaning is added 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?
States a specific verb (Get) and resource (LAG list) scoped to a switch stack, and enumerates what the result contains (member ports, load balancing mode, status). It does not distinguish itself from adjacent siblings such as getStackNetworkList or listSwitchNetworks, which an agent may reasonably confuse for related stack-level list calls.
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?
Gives a concrete prerequisite chain: use getSwitchStackDetail to obtain the stackId. It does not state when to prefer this over the other stack/network listing tools, nor any when-not conditions, so selection against alternatives still requires inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getPastClientNumBRead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | End of the time range as Unix epoch seconds. | |
| start | Yes | Start of the time range as Unix epoch seconds. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral fact that the result is a time-series rather than a scalar snapshot, but it says nothing about granularity, bucketing, aggregation, latency, or whether large ranges are truncated.
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, front-loaded with the core purpose. There is mild redundancy between "over a time range" and "over the specified period" plus a restatement of the epoch-second format, but nothing that obscures the intent.
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 three-parameter read tool with no output schema, the description covers what is returned (a time-series of client counts) and the required inputs, which is enough to call it correctly. Only the resolution/aggregation semantics of the series are left unstated.
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%, including the siteId fallback to OMADA_SITE_ID and the listSites discovery hint, so the schema carries parameter meaning fully. The description only restates that start and end are Unix epoch seconds, adding no semantics 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+resource ("Get historical client count trend") and states the unit of return (a time-series of connected-device counts), so an agent knows exactly what it retrieves. It does not, however, distinguish itself from plausible siblings such as getGridClientHistory, getClientsDistribution, or listClientsPastConnections, which a reader would have to open to disambiguate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance beyond the trivial requirement of a time range, and no mention of which sibling to prefer for a different client-count view. The only conditional information presented (start/end required, epoch seconds) is already in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getQosPolicyBRead-only
Get the gateway QoS policy (tag outbound traffic settings) for a site, including DSCP marking rules for outbound traffic.
| 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. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the payload contains DSCP marking rules for outbound traffic, which is useful content context, but says nothing about whether a default site is silently substituted or what happens when no policy is configured. The schema covers the siteId default, so this is a modest addition rather than a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence with the resource named first, which is the right front-loading for a lookup tool. The phrase 'outbound traffic' appears twice, which is slightly redundant, but nothing else is wasted.
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 read-only, single-optional-parameter getter with no output schema, the description supplies enough: what is fetched, at which scope, and the headline content (DSCP rules for outbound traffic). Only the absent-configuration behavior and the relationship to overlapping QoS tools are left uncovered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single siteId parameter is fully documented in the schema, including the default-site fallback and the listSites discovery hint. The description adds no syntax or meaning beyond that, so the baseline 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?
States a specific verb and resource (get the gateway QoS policy) scoped to a site, and parenthetically clarifies the content as outbound traffic tagging with DSCP marking rules. It is clearly a read of gateway-level QoS rather than the AP-level or class-rule siblings, though it never names those siblings 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?
There is no when-to-use guidance and no routing to alternatives such as getApQosConfig, getGatewayQosClassRules, or getTrafficPriority, all of which live in the same domain and are easy to confuse with this tool. The only usage signal is the implicit 'read a site's QoS policy' framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getRadiosConfigARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context by enumerating the returned configuration fields and contrasting configuration versus runtime state, which goes beyond the annotations. It does not mention pagination or error behavior, but neither is material for a per-AP read.
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 tight sentences with the core purpose front-loaded, followed by return contents and then the disambiguation from the sibling. No redundant or filler wording.
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?
With no output schema, the description compensates by enumerating the returned settings, and it covers the distinction from the closest sibling plus the MAC prerequisite via the schema. Nothing an agent needs to call this correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (apMac, siteId) are documented including format and discovery hints in the schema itself. The description adds no parameter-level detail beyond the schema, so the 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 opens with a specific verb and resource ('Get per-radio configuration for an access point') and immediately clarifies the returned data (band, channel, transmit power, channel width, enabled SSIDs). It explicitly differentiates itself from the sibling getApRadios, so an agent can distinguish the two without inspecting either schema.
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?
It names the alternative (getApRadios) and states the exact condition that selects it: runtime radio status versus configuration. The schema also points to listDevices for obtaining the apMac, covering the prerequisite for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getRadiusProxyConfigARead-only
Get the global RADIUS proxy configuration from the controller, including proxy enabled state and server settings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds useful content context by naming what the payload includes (proxy enabled state and server settings), but says nothing about permissions, sensitivity of RADIUS secrets, or response shape. Given annotation coverage, this is adequate but not rich.
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?
A single front-loaded sentence with the verb and resource leading. 'From the controller' is mildly redundant given the tool name, but it usefully clarifies the source of truth; the trailing clause listing the returned fields 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?
For a zero-parameter read tool with no output schema, the description covers enough: what is fetched, from where, and roughly what the response contains. Additional detail such as error behavior when no proxy is configured would help, but is not essential to call it correctly.
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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description conflicts with the empty 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?
States a specific verb ('Get') and a specific resource ('global RADIUS proxy configuration from the controller'), and the 'global' qualifier distinguishes it from any per-site configuration. No sibling tool in the list covers RADIUS proxy, so the resource itself does the differentiation, though the description never names a sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the 'global' qualifier suggests this is the controller-wide view rather than a site-scoped one, but there is no explicit when-to-use, when-not, or alternative tool referenced. An agent can infer the use case from the name and description, which is the definition of minimum-viable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getServerCapabilitiesARead-only
Report this server version, effective catalog, profile and validation limits. Does not claim live controller compatibility.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a genuine caveat beyond the annotations — that it does not claim live controller compatibility — which sets correct expectations, but it says nothing about freshness of the reported limits or any cost/latency of the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, and the primary content (what gets reported) is front-loaded ahead of the caveat. Nothing is wasted.
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 parameterless, read-only introspection tool with no output schema, the description adequately signals the categories of data returned. A slightly richer account of the return shape would help, but the absence of an output schema is a minor gap for a tool this simple.
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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description does not misrepresent any inputs.
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 names a specific verb ("Report") and enumerates the concrete resources returned: server version, effective catalog, profile and validation limits. That distinguishes it from every sibling tool, which are all device/network data readers, though it never explicitly says it is a server-introspection/metadata tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the tool to call to learn what the server supports. There is no explicit statement of when to prefer it, no mention of calling it first before other operations, and no named alternative it replaces.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsAvailableChannelBRead-only
Get available channels for an AP.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a read-only, non-destructive operation. The description adds only the basic notion of retrieving available channels and does not explain the return shape, whether results are per radio/band, prerequisites, or any rate/permission 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?
The definition is a single front-loaded sentence with no wasted wording. It is concise and easy to scan, even though brevity contributes to gaps assessed under other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with full schema coverage and read-only annotations, the definition is minimally adequate. However, it does not characterize the returned 'available channels' data and has no output schema to compensate, leaving a meaningful gap for an agent invoking it.
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 both apMac and siteId in detail, including examples and discovery hints. The description adds no parameter meaning beyond the schema baseline, so a 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 states a specific verb and resource: getting available channels for an AP. It is clear enough for an agent to understand the core operation, but it does not distinguish this tool from related siblings such as getSitesApsChannelLimit or getApRadios.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no when-not-to-use guidance, and no alternatives named. The only usage information is implied by the phrase 'for an AP', which is insufficient given the many adjacent channel, radio, and AP-configuration tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsBridgeCRead-only
Get P2P bridge config for an AP.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered externally. The description adds nothing further — no indication of what the bridge config contains, whether it can be empty, or what errors occur for an AP without bridging enabled.
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?
A single short sentence with the resource front-loaded and no redundant wording. It is efficient, though its brevity borders on under-specification rather than optimal tightness.
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, so the description is the only place to explain what 'P2P bridge config' returns, yet it does not. For a simple read tool with fully documented params this is not fatal, but the undefined jargon leaves an agent unable to predict the shape or content of 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?
Schema coverage is 100%: apMac has a pattern and example plus a pointer to listDevices, and siteId documents the OMADA_SITE_ID default and listSites. The description contributes no extra parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb ('Get') and a specific sub-resource ('P2P bridge config for an AP'), which distinguishes it from generic AP getters like getApDetail or getApUplinkConfig in the sibling list. It stops short of naming a sibling, but the resource is narrow and identifiable.
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 the many other AP config getters (getApVlanConfig, getApQosConfig, etc.), and no prerequisites or exclusions are mentioned. The agent must infer usage purely from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsChannelLimitCRead-only
Get channel limit config for an AP.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say whether the limit is per-radio or per-AP, what happens when no limit is configured, or what the config payload resembles, which is the kind of context a getter description should supply.
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?
A single front-loaded sentence with zero filler or repetition. It is efficient, though its brevity contributes to the gaps noted elsewhere rather than being a defect of structure.
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?
This is a low-complexity, two-parameter, read-only getter with fully documented parameters and no output schema, so the burden on the description is modest. Still, it says nothing about the returned config or the unset case, which an agent would want before relying on 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?
Schema coverage is 100% and the schema descriptions are strong, including the MAC pattern, the default-site fallback for siteId, and cross-references to listDevices and listSites. The description adds no meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('Get') and a specific resource ('channel limit config') scoped to an AP, which is enough to tell it apart from most getters. It does not, however, distinguish it from the near-sibling getSitesApsAvailableChannel or clarify what 'channel limit' means (allowed-channel list vs. per-radio limit), leaving a small ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no exclusions, and no pointer to alternatives such as getSitesApsAvailableChannel or getRadiosConfig. The agent must infer from the name alone when this getter applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsIpSettingCRead-only
Get IP settings for an AP.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say what settings are returned, whether the AP must be online, or how the per-site scoping behaves.
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?
A single front-loaded sentence with zero redundancy. It is efficiently structured, though the brevity comes at the cost of specificity rather than being padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with full schema coverage and annotations, the definition is minimally viable. It is still thin on what the returned IP settings include and how it differs from the many sibling AP-configuration getters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both apMac and siteId are documented in the schema with format hints and pointers to listDevices/listSites. The description adds no parameter meaning beyond the schema, so the 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?
States a specific verb and resource (get IP settings for an AP), so the basic action is clear. However, it does not distinguish this from close siblings such as getApIpv6Config, getApGeneralConfig, or getApVlanConfig, leaving ambiguity about whether 'IP settings' means IPv4 address, DHCP mode, or something else.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of any alternative tool. An agent must infer from the name alone that this is the tool for AP IP configuration rather than IPv6 or general AP config.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsLoadBalanceCRead-only
Get load balance config for an AP.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that—no note on what the config contains, whether it requires the AP to be online, or any failure behavior. For a read-only getter the bar is lower, but zero added context earns a 2.
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?
A single front-loaded sentence with no wasted words. It is terse to the point of under-specification, but structurally clean.
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?
A simple read-only getter with fully documented parameters and no output schema, so the description needn't explain return values. However, 'load balance config' is left undefined, so the agent cannot anticipate what fields come back or how to interpret them.
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 apMac and siteId fully documented including format examples and discovery hints (listDevices, listSites). The description adds no parameter meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Get) and resource (load balance config) scoped to an AP, so the agent knows what it retrieves. It does not differentiate from the many sibling getAp*Config tools (getApUplinkConfig, getApQosConfig, etc.), leaving the agent to infer which config this covers.
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 when-to-use guidance, no prerequisites, and no mention of alternatives among the numerous AP config getters. The agent must guess that this is the right tool for load-balance settings versus other AP config tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsOfdmaCRead-only
Get OFDMA configuration for an AP.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally, and the description merely restates that with the word "Get." It adds no context about what the OFDMA configuration contains (per-radio settings, enabled/disabled state), whether it requires the AP to be online, or how errors surface for an unknown MAC.
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?
A single front-loaded sentence with zero filler, which is efficient. The brevity borders on under-specification rather than verbosity, but there is no wasted wording to trim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with fully documented parameters and clear safety annotations, this is close to sufficient. Still, with no output schema, an agent gets no sense of the shape or granularity of the returned OFDMA configuration, which is the one meaningful 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 description coverage is 100%, including the MAC pattern and example plus the default-site fallback behavior, so the schema carries the parameter semantics fully. The description contributes nothing beyond that, making the baseline 3 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 states a specific verb and resource (get OFDMA configuration) scoped to an AP, which is unambiguous on its own. It does not, however, distinguish itself from the many sibling getters such as getRadiosConfig or getApQosConfig, so an agent must rely on the name alone to pick it out of the AP-config cluster.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any noted prerequisites. The only routing help (use listDevices to find AP MACs, listSites for site IDs) lives in the schema parameter descriptions, not the tool description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsPowerSavingBRead-only
Get power saving config for an AP.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered and the description does not contradict it. Beyond that the description adds nothing: no statement of what the config contains, whether it is site-scoped or device-scoped, or what happens when the AP is offline.
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 front-loaded sentence with zero filler; nothing is redundant or buried. The brevity is a structural strength even though content is thin elsewhere.
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 low-complexity, read-only, two-parameter getter with 100% schema coverage and no output schema, the description covers the essentials of what is retrieved. The remaining gap is which fields the power saving config returns, which is minor at this complexity level.
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 both apMac (with format and a listDevices pointer) and siteId (with default-site fallback and listSites pointer) are already fully documented in the schema. The description adds no syntax, format, or defaulting information beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('Get') and a specific resource ('power saving config for an AP'), which is more precise than the ambiguous tool name. However, it never distinguishes this from the many sibling AP-configuration getters (getApGeneralConfig, getSitesApsLoadBalance, getSitesApsOfdma), so an agent must infer the boundary from names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives or when not to use it. The only routing help ('Use listDevices to find AP MACs') lives in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsTrunkSettingCRead-only
Get trunk setting for an AP.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
C2.5/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond restating the title: it doesn't say what the trunk setting contains, whether an AP without trunk config returns empty, or anything about per-site scoping.
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?
One short sentence is front-loaded and free of padding, but it is terse to the point of under-specification rather than genuinely concise. There is room for a clause explaining what a trunk setting is in this domain.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining what comes back, and it doesn't. An agent knows only that some trunk setting is retrieved for a given AP MAC; it cannot anticipate the shape or interpret an empty 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?
Schema description coverage is 100%, and the two parameters (apMac, siteId) are fully documented with formats and discovery hints in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a verb ("Get") and a resource ("trunk setting for an AP"), so the basic purpose is inferable. However, "trunk setting" is left undefined, and among dozens of sibling tools like getApUplinkConfig, getSitesApsBridge, and getApGeneralConfig there is nothing to tell an agent which AP setting family this returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many adjacent AP-configuration getters, nor any stated prerequisites. The only routing help (use listDevices / listSites) lives in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesDeviceWhiteListCRead-only
Get the device whitelist for a site.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: no mention of pagination behavior (despite page/pageSize), result ordering, or what an empty whitelist looks like, which is all the more relevant since there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler. It is efficient, though its brevity is partly the cause of the missing usage and behavioral detail rather than a sign of disciplined compression.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, zero-required-parameter list tool with fully documented schema and no output schema, the description is minimally viable. However, it omits pagination semantics and return shape, and gives no hint about how 'device whitelist' differs from the many adjacent allow-list tools, leaving real 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 description coverage is 100%, with page, pageSize, and siteId all fully documented including defaults, bounds, pattern, and the listSites discovery pointer. The description contributes no additional parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: retrieve the device whitelist for a site. It is clear what the tool returns conceptually, but it does not differentiate itself from nearby defensive/allow-list siblings such as getGridAllowList, getGridBlockList, or getUrlFilterWhitelist, so an agent must infer the distinction from names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives — nothing distinguishes it from the many other whitelist/ACL retrieval tools in the sibling list. The only implied usage is the schema's note that siteId falls back to a configured default, which is not repeated or expanded in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesGatewaysGeneralConfigCRead-only
Get gateway general config.
| 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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find gateway MACs. |
TDQS
C2.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is carried by structured data. The description adds nothing further: it does not say what configuration fields are returned, whether the call is cached, or whether it requires the gateway to be online.
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?
It is a single sentence with no wasted words, but the brevity comes from omission rather than efficiency. There is no front-loaded scope statement or qualifier to anchor the agent.
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 only two parameters, full schema coverage, annotations, and no output schema, the structured fields carry most of the load — but the description still leaves the tool's scope ambiguous against several sibling getGateway* and *GeneralConfig tools. A single clause describing what 'general config' contains would close the 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 description coverage is 100%, and the parameter descriptions already explain the siteId default via OMADA_SITE_ID and point to listSites/listDevices for discovery. The description adds no meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description essentially restates the tool name: 'Get gateway general config' adds no information beyond getSitesGatewaysGeneralConfig. It does not distinguish this from close siblings such as getGatewayDetail, getSwitchGeneralConfig, or getApGeneralConfig, so an agent cannot tell which 'general config' surface it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance at all — no condition that selects this over getGatewayDetail, getGatewayWanStatus, or getGatewayLanStatus. The agent must infer scope purely from the name and the gatewayMac/siteId parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesGatewaysPinBRead-only
Get PIN setting for a gateway (LTE model).
| 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. | |
| 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
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description contributes the LTE-model applicability constraint, which is not in the annotations, but adds nothing about permissions, error behaviour, or what the PIN value represents (device PIN vs SIM PIN).
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?
A single short sentence with the resource front-loaded and no filler. It is efficient, though the terseness comes at the cost of context rather than being maximally informative.
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?
This is a simple two-parameter read with no output schema and covered annotations, so the description does not need to explain return values. However, it leaves the key ambiguity of what a gateway "PIN setting" actually is, which matters for an agent deciding whether this is the right 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%: siteId's default-site fallback and gatewayMac's format plus the listDevices discovery hint are all documented in the schema. The description adds no meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ("Get PIN setting for a gateway") and adds a scoping qualifier ("LTE model") that separates it from the many other getSitesGateways* siblings. It does not explicitly name a neighbouring alternative, but the resource is narrow enough that an agent can identify what it retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The parenthetical "(LTE model)" is an implied applicability constraint but it is never stated as a rule, leaving the agent to infer that non-LTE gateways are out of scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesGatewaysSimCardUsedCRead-only
Get SIM card used by a gateway.
| 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. | |
| 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond them — no indication of what SIM data is returned, whether the gateway must be online, or any failure behavior. With annotations present, the bar is lower, but this adds zero extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no wasted words, but it is so terse that nothing is front-loaded beyond the bare purpose. Efficient though under-informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only two-parameter tool with full schema coverage and no output schema, the description is minimally adequate. It doesn't clarify what the SIM card result contains, which would help an agent decide whether to call it, but complexity is low enough that 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 description coverage is 100%, and both parameters (siteId and gatewayMac) are fully documented with patterns and discovery hints (listSites, listDevices) in the schema itself. The description adds no meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: retrieves the SIM card information used by a gateway. An agent can distinguish this from siblings like getGatewayDetail or getGatewayWanStatus, though it doesn't explicitly say how it differs from those broader gateway 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?
Provides no when-to-use guidance, no prerequisites, and no mention of alternatives. It doesn't explain when to prefer this over getGatewayDetail or other gateway queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesHealthGatewaysWansDetailsBRead-only
Get WAN port health details for a gateway.
| 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. | |
| 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
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the scope ('WAN port health details'), and says nothing about what the health details contain, whether data is live or historical, or any rate/permission 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?
A single front-loaded sentence with no filler, which is appropriate for a simple two-parameter read tool. It is efficient but borders on under-specified rather than maximally informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with full schema coverage and annotations, the description is adequate but thin: it never clarifies what 'health details' includes or how it differs from the other gateway health tools. No output schema exists, so a brief note on the returned data would have helped.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema itself explains siteId fallback behavior and how to find gateway MACs via listDevices. The description adds no parameter meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get WAN port health details') scoped to a gateway, so an agent knows exactly what data it returns. It does not, however, distinguish itself from close siblings such as getGatewayWanStatus or getGatewayHealth, which an agent could easily confuse it with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus getGatewayWanStatus, getGatewayHealth, or getGatewayDetail, all of which appear in the sibling list. The agent must infer the distinction from names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesSwitchesEsCRead-only
Get easy managed switch info.
| 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. | |
| 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral detail beyond that — it doesn't say what data is returned, whether it is site-scoped, or how it differs from a full switch detail read.
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?
One short sentence with no wasted words, but it is under-specified rather than concise. Brevity here costs information rather than saving it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is the only place to learn what 'info' comprises, and it says nothing. For a per-switch lookup tool that overlaps heavily with switch siblings, this leaves the agent unable to judge what it will get back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both siteId and switchMac are documented with patterns and discovery hints (listSites, listDevices). The description adds nothing beyond the schema, so the 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 has a verb ('Get') and a resource ('easy managed switch info'), and 'easy managed' hints at a specific switch class. But 'info' is vague about what is actually returned, and nothing distinguishes it from the many sibling retrieval tools such as 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?
There is no guidance on when to use this tool rather than getSwitchDetail, getSwitchGeneralConfig, or the other switch-related siblings. The agent must infer the use case 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.
getSitesSwitchesEsGeneralConfigCRead-only
Get easy managed switch general config.
| 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. | |
| 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered elsewhere; the description adds nothing on top of that. It does not say what the 'general config' payload contains, whether it differs by switch model, or whether a device must be online — all meaningful for a read 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no padding, but it is terse to the point of under-specification rather than efficiently informative. Nothing is front-loaded beyond a bare restatement of the name.
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, so the description was the only place to explain what the returned config actually contains, and it omits that entirely. Given the sibling getSwitchGeneralConfig and the ambiguity of the 'Es' scope, an agent lacks the information needed to call this with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters carry explicit guidance (siteId fallback to OMADA_SITE_ID, switchMac format and listDevices pointer), so the schema does the heavy lifting. The description contributes no additional parameter meaning, which is the expected baseline of 3 at full 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?
States a verb ('Get') and a resource ('easy managed switch general config'), so the broad intent is retrievable, but 'easy managed' / 'Es' is unexplained jargon and the description never distinguishes this from the sibling getSwitchGeneralConfig. An agent cannot tell from the text which of the two switch-config tools applies to a given device.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this rather than getSwitchGeneralConfig, getSwitchDetail, or getSitesSwitchesEs, nor any prerequisite stated. The only usage hints (siteId default, MAC lookup) live in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSpeedTestResultsARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that safe-read profile. It adds real behavioral context beyond the annotations: the values come from a prior test rather than being measured on demand, and it names the returned metrics (upload/download throughput). It stops short of describing what happens when no speed test has ever run.
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 short sentences, each earning its place: what it returns, what the return values are, and which sibling to use for a new measurement. The key scoping fact is front-loaded with zero 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?
For a two-parameter read tool with no output schema, the description covers the essentials: the resource, the returned metrics, and the trigger-vs-read split. It could be slightly more complete by noting behavior when no stored result exists or whether results are timestamped.
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%: apMac includes a format example and a pointer to listDevices, and siteId explains the OMADA_SITE_ID default and listSites discovery. The description adds nothing parameter-specific, so the schema does all the work and the 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 states a specific verb and resource ("Get the last speed test results for an access point") and immediately clarifies the payload (upload/download throughput from the most recent test). It explicitly distinguishes this read path from the triggerSpeedTest sibling, so an agent can choose between them without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It routes the agent clearly: use triggerSpeedTest to start a new test, this tool returns stored results. That is an explicit alternative plus the condition that selects it. The only gap is no guidance on the empty/never-tested case, which would matter in practice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getStackNetworkListARead-only
Get the VLAN network list for a switch stack. Returns VLAN interface assignments across all stack members. Use getSwitchStackDetail to get the stackId.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| stackId | Yes | Stack ID of the switch stack. Use getSwitchStackDetail to find the stackId. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a small amount of behavioral context by noting the result covers VLAN interface assignments across all stack members, but says nothing about result size, pagination behavior, or whether empty stacks return an error.
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 short sentences with the core purpose front-loaded and the prerequisite hint immediately after. The stackId sentence largely duplicates the schema description, which is a minor redundancy rather than clutter.
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-only list tool with full schema coverage and safety annotations, the definition covers what is being fetched and how to obtain the required ID. A brief note on pagination or what an empty stack returns would close the remaining gap, but nothing essential is missing.
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 all four parameters, including siteId fallback and page/pageSize limits, are already documented. The description's only parameter-adjacent content is the stackId discovery hint, which the schema itself repeats, so it adds no meaning beyond the structured fields.
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 names a specific verb and resource ('Get the VLAN network list') and scopes it to a switch stack, with a follow-on sentence clarifying that results span all stack members. It is clear enough to separate from getSwitchStackDetail, though it never explicitly distinguishes itself from the sibling listSwitchNetworks, which an agent could easily confuse it with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete prerequisite path: 'Use getSwitchStackDetail to get the stackId.' That tells an agent how to obtain the required parameter. It stops short of stating when to prefer this over listSwitchNetworks or other switch-network tools, so there is no exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getStackPortsCRead-only
Get all port information for a switch stack.
| 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. | |
| stackId | Yes |
TDQS
C2.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds nothing beyond that: it does not say what 'port information' includes (status, PoE, VLAN, link speed), whether results are paginated or complete, or what happens when the stack has no ports.
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?
A single front-loaded sentence with no filler or redundancy. Its brevity is efficient, though it borders on under-specification rather than earning every word through useful detail.
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 is simple (two parameters, read-only, no output schema), so a short description is defensible, and annotations carry the safety profile. Still, an agent gets no signal about the return payload or how stack port data differs from the sibling port/detail tools, leaving a meaningful gap for an otherwise easy tool.
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 50%: siteId is well documented in the schema, but stackId has no description and its pattern admits ':' and '-' separators, hinting at a composite identifier that the description never explains. The phrase 'for a switch stack' only restates the parameter name and does not compensate for the undocumented 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?
States a specific verb and resource: retrieve all port information for a switch stack. That is unambiguous on its own, but it draws no boundary against nearby siblings such as getSwitchStackDetail, getGatewayPorts, or listSitesApsPorts, so an agent must infer which port endpoint applies to stacks versus gateways or APs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no exclusions, and no mention of alternatives among the many sibling tools. It also does not note that siteId falls back to OMADA_SITE_ID when omitted, a scoping behavior the agent would have to discover from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSwitchDetailARead-only
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.
| 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. | |
| 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds that this is a comprehensive snapshot covering many subsystems, but says nothing about whether siteId omission falls back to a default site, response size, or rate limiting. Adequate but with room to say more.
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 tight sentences: the capability and returned fields come first, then the prerequisite pointer. No filler, no redundancy with the title or annotations.
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 read-only two-parameter lookup with full schema coverage and no output schema, the definition covers purpose and prerequisite well. The only gap is disambiguation from the many sibling switch-detail tools and a note that the response is large and comprehensive.
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 both parameters are already documented in the schema, including the MAC format and the OMADA_SITE_ID fallback. The description reinforces the switchMac sourcing (via listDevices), adding modest navigational value but no new 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?
States a specific verb (Fetch) and resource (full configuration and status for a specific switch), then enumerates exactly what is returned: model, firmware, CPU/memory, port states, PoE usage, VLAN config, STP status. This clearly distinguishes it from siblings like getSwitchGeneralConfig or getSwitchStackDetail, which cover narrower slices.
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?
Gives a clear prerequisite path by naming listDevices as the way to obtain the required switchMac. It does not, however, state when to prefer this over adjacent detail tools such as getSwitchStackDetail, getSwitchGeneralConfig, or getSwitchDot1xSetting, so the agent must infer boundaries from names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSwitchDot1xSettingBRead-only
Get the 802.1X switch port authentication setting. Controls port-based network access control on managed switches.
| 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. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a little domain context by explaining the setting governs port-based network access control on managed switches. It says nothing about scope, return shape, or whether defaults are merged in, so value beyond annotations is modest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and resource. The second sentence is slightly oblique ('Controls port-based network access control') and borders on restating the first, but nothing is verbose or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-parameter read tool with annotations and no output schema, the definition is barely sufficient. It never hints at what the returned 802.1X settings look like or how they relate to getDot1xConfig, which matters because there is no output schema to compensate. Adequate but with a clear 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 description coverage is 100%: siteId is documented with its pattern, the OMADA_SITE_ID default fallback, and a pointer to listSites. The description adds no meaning beyond that. With a single fully-documented parameter, the baseline 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 states a specific verb and resource: 'Get the 802.1X switch port authentication setting.' An agent knows exactly what entity is retrieved. However, it never distinguishes itself from the sibling getDot1xConfig, so an agent cannot tell which of the two to call based on purpose alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance beyond the resource name. Crucially, the sibling list contains getDot1xConfig, and the description gives no rule for choosing between 'switch port authentication setting' and that other 802.1X configuration tool. Nothing about prerequisites or expected context is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSwitchGeneralConfigARead-only
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.
| 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. | |
| 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
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds what the read actually contains (LED, LLDP, flow control, and other global switch parameters), which substitutes for the absent output schema; it stops short of noting auth requirements or whether values are site-scoped.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place: the field inventory comes first and the identifier-acquisition hint second. There is no filler or restated title.
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 read-only, two-parameter tool with a fully documented schema and no output schema, the description gives enough: it names the config domains returned and how to obtain the switch MAC. The catch-all "other global switch parameters" leaves the exact return set slightly open, which is the main residual 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 description coverage is 100% across both parameters, including the MAC format example, the siteId default from OMADA_SITE_ID, and the listSites/listDevices discovery hints. The description adds no semantics beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ("Get general configuration for a switch") and enumerates concrete fields — device name, LED settings, LLDP settings, flow control. It does not, however, distinguish itself from near-neighbours such as getSwitchDetail or getSitesSwitchesEsGeneralConfig, so an agent cannot tell from the text alone which switch-config getter to pick.
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 only usage guidance is "Use listDevices to get switchMac values", which tells the agent how to acquire the required identifier but not when to prefer this tool over alternatives or when it is not appropriate. The same pointer already appears in the switchMac schema description, so it adds little beyond structured data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSwitchStackDetailCRead-only
Fetch detailed information for a specific switch stack.
| 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. | |
| stackId | Yes |
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing further: it does not say what "detailed information" includes, whether the call fails for non-stack devices, or how large the payload typically is. For a read tool with annotations, that is a low-value contribution.
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?
A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity reflects under-specification rather than tight editing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is the only place to explain what the returned detail covers, and it says nothing. Combined with the undocumented required stackId, an agent cannot confidently tell whether this is the right tool or what it will receive.
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 50%: siteId is well documented in the schema, but stackId carries no description there. The description does not compensate by explaining where a stackId comes from (e.g., listSitesStacks) or its expected form, leaving the required parameter semantically bare.
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 names a verb ("Fetch") and a resource ("switch stack detail"), but it is essentially an expansion of the tool name getSwitchStackDetail and adds no distinguishing scope. It never clarifies how it differs from close siblings like getSwitchDetail, listSitesStacks, or getStackPorts, which an agent must choose between.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The agent is left to infer from the name alone that this is the stack-level lookup and not the single-switch or stack-port tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getTrafficDistributionARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | End of the time range as a Unix timestamp in seconds (e.g. Math.floor(Date.now() / 1000)). Must be paired with start. | |
| start | Yes | Start of the time range as a Unix timestamp in seconds (e.g. Math.floor(Date.now() / 1000) - 3600 for the last hour). Must be paired with end. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is conveyed structurally. The description adds the useful scoping detail that results are grouped by traffic category (video, gaming, web, etc.), but it says nothing about aggregation granularity within the range, cardinality of results, or the fact that omitting siteId falls back to a configured default site.
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 short sentences, front-loaded with what the tool returns before the explanatory benefit statement. The final timestamp sentence is largely redundant with the schema, which is the only real waste.
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 3-parameter read-only tool with full schema coverage and safety annotations, the description covers purpose, output dimension, and a concrete example of the categories returned, which partially compensates for the absent output schema. Missing only edge details such as granularity of the breakdown and default-site behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters including the siteId default behavior and the Unix-seconds format are already fully documented in the schema. The trailing sentence about start and end being Unix timestamps in seconds restates the schema rather than adding new meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Get traffic distribution") plus the dimensions it breaks down by (protocol and application type) over a time range, which is concrete enough to separate it from neighbors like getClientsDistribution or getDashboardTrafficActivities. It stops short of explicitly naming a sibling it is not, so a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause "helping identify what is consuming bandwidth on the network" implies the intended use case, and the required time range hints that this is a windowed analysis call. But there is no explicit when-to-use/when-not guidance and no pointer to an alternative tool for related questions such as per-client rather than per-category traffic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getTrafficPriorityARead-only
Get the gateway VoIP and traffic prioritization settings for a site, including QoS prioritization rules for voice and real-time traffic.
| 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. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful scope by naming which settings are returned (VoIP prioritization and QoS rules for voice/real-time traffic), but it says nothing about whether it returns effective vs configured values, defaults, or per-WAN behavior.
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?
A single front-loaded sentence, with the resource stated first and the qualifying detail about voice/real-time QoS rules second. No filler, though the trailing clause slightly overlaps the leading phrase.
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 read-only getter with one optional, fully documented parameter and no output schema, the description covers what the tool returns and where it applies. The only meaningful omission is sibling differentiation against the many other QoS-related getters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the siteId field documents the pattern, the OMADA_SITE_ID default when omitted, and the listSites discovery route. The description adds no parameter meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource and scope: gateway VoIP and traffic prioritization settings for a site, plus the QoS rules for voice and real-time traffic. It is clear what it reads, but it does not distinguish itself from closely named siblings such as getQosPolicy, getGatewayQosClassRules, or getBandwidthCtrlDetail, leaving the agent to guess which QoS getter to call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the read-and-inspect nature of the tool; there is no explicit statement of when to call this versus the other QoS and bandwidth tools in the sibling list. An agent can infer it is a configuration lookup, but the choice among near-duplicate siblings is left unresolved.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUpgradeLogsBRead-only
Get firmware upgrade logs showing the history of upgrade operations performed on devices.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the content is historical upgrade records, but says nothing about ordering, pagination behavior, how far back logs go, or whether results span all devices or a single device.
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?
A single front-loaded sentence with no filler or redundant restatement of the name. It is appropriately sized, though it could spend one more clause on routing rather than on re-describing 'upgrade operations'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter, read-only query with annotations covering safety and a fully documented schema, the essentials are present. However, the description leaves open whether logs are global or device-scoped and how much history is returned, which matters for a paginated log-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 both page and pageSize are fully documented in the schema and the baseline is 3. The description adds no meaning beyond that, and notably does not clarify the absence of any device or date filter, which an agent might otherwise assume exists.
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 and resource ('Get firmware upgrade logs') and narrows scope to the history of upgrade operations on devices. It clearly separates this from nearby siblings such as getFirmwareUpgradePlan or getFirmwareInfo, but never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance, and no mention of the several upgrade-related siblings (getFirmwareUpgradePlan, getFirmwareInfo, getGridAutoCheckUpgrade) an agent could pick instead. The read-only nature of the call can be inferred, but selection among the many upgrade tools is left entirely to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUpgradeOverviewCriticalARead-only
Get the number of critical firmware upgrades available across managed devices.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds two useful behavioral facts beyond that: the result is a count (not a detailed list) and the scope is limited to 'critical' severity upgrades across managed devices. It does not say whether the scope defaults to the whole organization or whether per-site/per-device breakdowns exist.
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 front-loaded sentence with no filler or redundant restatement of the tool name. Every clause carries meaning: criticality, availability, and device scope.
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 zero-parameter read-only counter with full annotation coverage and no output schema, the description is nearly sufficient. The only remaining ambiguity is whether the count is global or segmented, which is minor for a tool this simple.
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 tool takes zero parameters, so the baseline is 4 and there is nothing the description needs to disambiguate. The phrase 'across managed devices' correctly implies no filtering arguments are accepted.
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 a specific verb and resource: retrieve a count of 'critical firmware upgrades available across managed devices'. The word 'number' signals an aggregate count rather than a list, which implicitly separates it from siblings like listUpgradeOverviewFirmwares. However, it never names or contrasts with getUpgradeOverviewTryBeta, so an agent cannot be fully certain of the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of the alternative upgrade-overview tools (getUpgradeOverviewTryBeta, listUpgradeOverviewFirmwares, getFirmwareUpgradePlan), and no preconditions. An agent must infer the choice from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUpgradeOverviewTryBetaCRead-only
Get the try-beta firmware switch status for the controller.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description adds nothing: it does not say whether the status is per-site, per-controller, global, or what fields the status contains, which is the main thing an agent would want to know about a status-read endpoint.
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?
A single short sentence, front-loaded with the verb and resource, with no filler. It is efficient, though its brevity comes at the cost of substance rather than being a model of tightness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with no output schema, the description is short but leaves the central question unanswered: what 'switch status' actually means (on/off, beta enrollment state, per-controller flag) and what the caller receives. Adequate to identify the call, not adequate to interpret the result.
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 tool takes zero parameters, so the schema cannot supply semantics and the baseline is 4. The description correctly implies the controller scope without suggesting any inputs exist.
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 a verb ('Get') and a resource ('try-beta firmware switch status for the controller'), so the general purpose is identifiable. However, 'try-beta firmware switch status' is opaque terminology, and nothing distinguishes it from closely named siblings such as getUpgradeOverviewCritical, listUpgradeOverviewFirmwares, or getGridAutoCheckUpgrade.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this tool versus the many upgrade-related siblings, no prerequisites, and no exclusions. The agent must guess 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.
getUplinkWiredDetailARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the shape of the returned data, which is valuable, but says nothing about behavior when the AP is not wired-uplinked (mesh/wireless) or about error conditions such as an unknown MAC.
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 short sentences, scoped identically to the name and front-loaded with the return contents. No filler, though the trailing topology sentence is the weakest and could carry more routing value if it named a sibling.
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 two-parameter read-only tool with full schema coverage and no output schema, the description usefully summarizes the return fields and lets the schema handle the rest. It is nearly complete, missing only the edge case of APs without a wired uplink.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both params are documented there, including how to obtain apMac via listDevices and the siteId default from OMADA_SITE_ID. The description adds no parameter meaning beyond the schema, so the 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?
States a specific verb and resource (get wired uplink detail for an AP) and enumerates exactly what comes back: connected switch, port number, link speed, PoE status. That payload list differentiates it from configuration siblings like getApUplinkConfig and topology siblings like getDownlinkWiredDevices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'Useful for mapping physical network topology' implies a use case but names no alternatives and gives no when-not guidance. An agent must infer on its own whether to reach for this or getApUplinkConfig / getDownlinkWiredDevices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUrlFilterBlacklistARead-only
Get the MAC-based deny (blacklist) filter entries for a site (paginated). Returns MAC addresses blocked from network access.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of results per page (1–1000). |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are paginated and that returned values are MAC addresses blocked from network access, which is genuine value beyond the annotations, but it says nothing about max page behavior, empty-result semantics, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the verb and resource, followed by a single clarifying sentence on return content. No filler, no restatement of the tool name.
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-only, zero-required-parameter list tool with a fully documented schema and no output schema, the description supplies enough to call it correctly and to know roughly what comes back. The only missing piece is routing among closely related filter/ACL siblings.
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%, including the siteId fallback to OMADA_SITE_ID and the 1–1000 pageSize bounds, so the schema already carries the parameter semantics. The description only restates 'for a site (paginated)' and adds no format or default-override detail beyond what is documented.
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?
States a specific verb ('Get') and resource ('MAC-based deny/blacklist filter entries for a site'), and explicitly clarifies that the entries are MAC addresses rather than URL patterns, which disambiguates it from the URL-filter siblings despite the tool's name. It never names getUrlFilterWhitelist, getUrlFilterRules, or getMacFilterDetail directly, so sibling differentiation is implicit rather than stated.
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 phrase 'for a site' and '(paginated)' imply the context of listing deny entries within a site scope, but there is no explicit when-to-use or when-not-to-use guidance. Nothing tells the agent whether to prefer this over getMacFilterDetail or getUrlFilterRules when both appear relevant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUrlFilterGeneralARead-only
Get the URL filter global setting, including whether URL filtering is enabled and the default action for unmatched requests.
| 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. |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the description only needs to add context. It does add value by naming the two pieces of state returned (enabled flag and default action for unmatched requests), which matters because there is no output schema; it does not, however, discuss whether this reads a per-site or fleet-wide config beyond the 'global' wording.
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 resource being fetched and then specifies its contents. There is no filler, repetition of the tool name, or trailing qualification.
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 one-parameter, read-only getter with no output schema, the description is adequate: it identifies the resource and the return fields, and the schema handles the siteId semantics. It falls short only in not tying the tool to its sibling URL-filter endpoints, which an agent would need in order to route correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single optional siteId parameter with 100% schema description coverage, and the schema already explains the OMADA_SITE_ID fallback and points to listSites. The description adds nothing about the parameter, so the baseline of 3 applies since the schema carries the full burden.
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 and resource ('Get the URL filter global setting') and enumerates what the setting contains ('whether URL filtering is enabled and the default action for unmatched requests'). However, it never distinguishes this from closely named siblings such as getUrlFilterRules, getUrlFilterBlacklist, and getUrlFilterWhitelist, leaving the agent to infer that this one is the global toggle/state rather than a rule 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?
Usage is only implied by the word 'global' — an agent can guess this is the site-level on/off and default-action state rather than the per-rule endpoints. There is no explicit statement of when to call this versus getUrlFilterRules or the blacklist/whitelist tools, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUrlFilterRulesBRead-only
Get gateway URL filter rules for a site (paginated), listing URL-based allow/block rules applied on the gateway.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of results per page (1–1000). |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true and destructiveHint=false annotations already establish the safety profile, so the description need not restate it. It adds useful context that results are paginated and scoped to a gateway/site, but says nothing about ordering, total counts, or what a rule entry contains, and with no output schema that leaves gaps.
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?
A single sentence with no filler, and the core purpose plus pagination is front-loaded before the explanatory gloss. Slightly dense parenthetical insertion, but nothing that could be cut without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, three-parameter listing tool with full schema coverage and no output schema, the description covers purpose and scoping adequately. What is missing is the routing information an agent needs in a crowded gateway/filter sibling set: when this combined listing is preferred over the blacklist, whitelist, and general-config tools.
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 page, pageSize, and siteId are already fully documented, including the OMADA_SITE_ID default and the pointer to listSites. The description's only contribution is the word 'paginated', which merely flags that the schema's paging parameters matter. 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 pairs a specific verb (Get) with a specific resource (gateway URL filter rules) and adds scope (for a site, paginated) plus a gloss on what the resource means (URL-based allow/block rules applied on the gateway). It only implicitly differentiates from the close siblings getUrlFilterBlacklist and getUrlFilterWhitelist by implying a combined allow/block listing rather than stating the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the read path for URL filter rules on a gateway. There is no explicit when-to-use versus when-not, and no naming of the obvious alternatives (getUrlFilterBlacklist, getUrlFilterWhitelist, getUrlFilterGeneral) that a caller would need to choose between.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUrlFilterWhitelistBRead-only
Get the MAC-based allow (whitelist) filter entries for a site (paginated). Returns MAC addresses explicitly allowed through MAC filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of results per page (1–1000). |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds two useful facts beyond annotations — results are paginated and the payload is MAC addresses explicitly permitted through MAC filtering — but says nothing about ordering, total counts, or behavior when the allow list is empty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with the resource and scope front-loaded and no filler. Slightly more value could be extracted from the same length by naming the sibling it is confused with or clarifying URL-vs-MAC filtering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only, three-parameter list tool this is close to adequate, and the brief note on what is returned partly compensates for the absence of an output schema. It stops short of confirming the return structure (e.g. per-entry fields or pagination metadata) that the agent would otherwise get from an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including the page/pageSize bounds and the siteId default/enumeration hint via listSites, so the schema carries the parameter semantics. The description only echoes the pagination and site scope at a high level, adding no format or edge-case detail (e.g. page beyond last, pageSize maximum effect).
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?
States a specific verb and resource: retrieves allow-list (whitelist) entries for a site, and clarifies the entries are MAC-based and paginated. It does not disambiguate from similar siblings such as getMacFilterDetail, getSitesDeviceWhiteList, or getGridAllowList, and the 'getUrlFilterWhitelist' name sits oddly against the MAC-based framing, which may cause brief hesitation.
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 when-to-use guidance, no exclusions, and no pointer to a related or alternative tool. The agent must infer from the name and sibling list whether this is the URL-filter allow list or the MAC-filter allow list; nothing in the description resolves that routing decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listClientsARead-only
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.
| 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. |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and destructiveHint annotations already establish that this is a safe read operation. The description adds useful return-field detail and clarifies current connected scope, but it omits pagination, rate limits, and whether “all” results are truly unpaged.
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 front-loaded across three efficient sentences with no wasted wording. The return-field list is long but justified because there is no output schema.
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 low-complexity tool with one optional parameter, the description covers purpose, returned fields, and usage context adequately. The main missing piece is pagination or result-limit behavior for a list-all operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional siteId parameter, including the default-site behavior and listSites discovery hint. The description only implies site scoping and adds no parameter meaning 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 gives a specific verb and resource: listing network clients, scoped to a site and covering wired and wireless devices. It is clear, but it does not explicitly distinguish itself from siblings such as getClientDetail, listMostActiveClients, or 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?
It states clear usage contexts: auditing connected devices or finding a specific client by name or MAC. It does not name when-not-to-use cases or a specific alternative sibling, and the name/MAC lookup relies on filtering the returned list because the schema has no search parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listClientsActivityARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Optional end timestamp in seconds (e.g., 1682000000) | |
| start | No | Optional start timestamp in seconds (e.g., 1682000000) | |
| siteId | No | Optional site ID. If not provided, uses the default site from configuration. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value by describing the return shape (per-snapshot counts of new, active, and disconnected clients split by EAP vs switch), but it says nothing about default time window behavior, pagination, or sampling granularity.
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 short sentences, front-loaded with the core action and scope. The final sentence largely restates the earlier 'activity statistics over time' framing, so there is minor redundancy but nothing bloated.
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 no output schema, the description must carry the return-value burden, and it does so by enumerating the metrics per time snapshot. For a read-only, three-optional-parameter tool this is close to sufficient; only default time-range behavior and the granularity of snapshots are left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all three parameters (start, end, siteId) are documented in the schema with units and defaults. The description adds no further parameter meaning — it never mentions the time range or site scoping — so the baseline 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 gives a specific verb and resource ('Get client activity statistics over time from the dashboard') and even narrows the payload to new/active/disconnected clients across wireless and wired. It does not, however, contrast itself with close siblings such as listMostActiveClients, getClientsDistribution, or getPastClientNum, so an agent still has to infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Useful for monitoring client connection trends and activity patterns' implies the monitoring use case but never states when to pick this over the many other client-statistics siblings, nor any exclusions or prerequisites. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listClientsPastConnectionsARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| guest | No | Filter by guest status (true/false). | |
| siteId | No | Optional site ID. If not provided, uses the default site from configuration. | |
| timeEnd | No | Filter by time range end timestamp (milliseconds). | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| searchKey | No | Fuzzy search by name, MAC address, or SSID. | |
| timeStart | No | Filter by time range start timestamp (milliseconds). | |
| sortLastSeen | No | Sort by last seen time. Values: asc or desc. When multiple sorts exist, first one takes effect. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the nature of the returned data (timestamps, traffic, duration, device details), but says nothing about rate limits, permissions, empty-result behavior, or whether history retention is bounded.
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, front-loaded with the core purpose and followed by return contents and capabilities. Every sentence carries information; only the capability sentence partially duplicates the schema.
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 read-only list tool with eight fully documented parameters and no output schema, the description covers purpose, returned fields, and available filtering/sorting, which is sufficient to invoke it correctly. Minor gaps (siteId defaulting, result ordering default) are the only omissions.
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 all eight parameters, their ranges, defaults, and the enum are already documented structurally. The description only restates those capabilities in aggregate (filtering, sorting, search) without adding format or interaction details, and it omits mention of siteId's default-site fallback.
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 opens with a specific verb and resource ('Get client past connection list') and immediately clarifies that these are historical connections, which separates it conceptually from live-client siblings like listClients or getClientDetail. It never names an alternative tool explicitly, so the differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It lists the capabilities (pagination, time-range and guest filtering, sorting, fuzzy search), which implies when the tool is useful, but gives no explicit when-to-use/when-not guidance and does not route the agent to or away from any of the many sibling client tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listDevicesARead-only
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.
| 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. |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and destructiveHint=false already covering the safety profile, the description still adds real value by scoping the result to adopted devices only and predicting the exact fields returned (MAC, model, firmware, IP, uptime, CPU/memory, status). It does not mention pagination or result-size behavior for large sites, which is the main remaining gap.
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 the verb and scope, then the return payload, then the follow-up routing. Every sentence supplies information the agent needs and none repeats the schema or annotations.
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?
For a single-parameter, read-only listing tool with no output schema, the description supplies the scope, the shape of the response, and the natural next call. Nothing an agent needs in order to invoke it correctly is missing.
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 siteId property already documents the default-site fallback and the listSites discovery path, so the description carries no additional parameter burden. Its phrase 'in a site' merely restates the parameter's role, so the 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 states a specific verb and resource ('List all provisioned (adopted) network devices in a site') and enumerates the three device classes covered. The word 'provisioned (adopted)' distinguishes it from the sibling listPendingDevices, and the whole-site enumeration distinguishes it from per-device getters like getSwitchDetail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear downstream guidance: the MAC addresses returned should be fed into getGatewayDetail, getSwitchDetail, getApDetail or similar. It does not explicitly contrast with searchDevices or listDevicesStats, so the agent must infer when to prefer searching or stats over a full listing, but the intended workflow is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listDevicesStatsARead-only
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).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| filterTag | No | ||
| searchSns | No | ||
| searchMacs | No | ||
| searchNames | No | ||
| searchModels | No | ||
| filterDeviceSeriesType | No |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a read-only, non-destructive operation. The description adds pagination and fuzzy-search behavior, but it does not explain the returned statistics, permissions, scope constraints, or limits beyond filtering.
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 tight sentences, front-loaded with the main purpose and then the supported search/filter dimensions. There is no redundant or filler wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an eight-parameter read-only tool with no output schema, the description covers the main filtering and search parameters but leaves the nature of the returned statistics vague. An agent can invoke it, but may not fully know what statistical output 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 coverage is only 25%, so the description must compensate for undocumented parameters. It does so well by mapping fuzzy search to MAC address, name, model, and serial number, and by explaining tag and device-series filtering with the 0/1 series codes.
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 a specific verb and resource: query statistics for global adopted devices. It implies a statistical view rather than a plain device listing, but it does not explicitly differentiate itself from siblings such as listDevices, searchDevices, or getAllDeviceBySite.
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 explains supported search and filtering capabilities, which implies usage for filtered device-stat queries. However, it gives no explicit when-to-use guidance or comparison against the many sibling device-listing and search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listEapAclsARead-only
List EAP (access point) ACL rules for a site: wireless client access control rules. Returns rule name, action (allow/deny), SSID scope, source/destination, protocol, and enabled state.
| 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. |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a safe read-only operation, and the description adds useful behavioral detail by naming the returned fields: rule name, action, SSID scope, source/destination, protocol, and enabled state. It does not discuss pagination or ordering, but it substantially improves visibility into the result beyond what the annotations provide.
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 front-loaded and compact: it states the resource scope first, then lists the returned fields in one concise clause. There is no redundant or filler wording.
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 read-only list tool with one optional parameter, annotations covering safety, and no output schema, the description is nearly complete because it explains the resource and enumerates returned fields. It could mention whether results are paginated or unfiltered, but the core context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single siteId parameter is fully documented there, including its pattern, default-site behavior, and discovery via listSites. The description adds no parameter-specific semantics, so the schema baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: list EAP ACL rules for a site, and clarifies that these are wireless client access control rules. This distinguishes it from generic ACL and firewall siblings by naming the EAP/wireless ACL scope.
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 site scope implies when to use it, but the description gives no explicit guidance on choosing between this and ACL-related siblings such as getGridEapRule, getOswAclList, or listOsgAcls. Usage is inferable from the name and purpose but not routed against alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listMostActiveClientsARead-only
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.
| 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. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that this is a dashboard/overview endpoint returning a ranked list, which is useful context, but it does not disclose how many clients are returned, whether the list is capped or truncated, or what happens when a site has no traffic data.
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, front-loaded with the core behavior and return fields. The final sentence ('quick overview of top clients by traffic usage') largely restates what the first two sentences already said, so it does not fully earn 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?
There is no output schema, so the description usefully enumerates the returned fields (name, MAC, type, model, wireless status, total traffic), which is exactly what an agent needs to decide relevance. The only meaningful gap is the absence of any indication of how many 'most active' clients are returned.
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% and the single siteId parameter is already fully documented, including the OMADA_SITE_ID default and the pointer to listSites. The description adds nothing about the parameter, but at full coverage and with the schema handling defaults and discovery, this is adequate; the description's enumeration of return fields partially compensates.
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 names a specific verb and resource ('Get the most active clients in a site') plus the sort order ('sorted by total traffic'), and enumerates the returned fields. That distinguishes it from generic siblings like listClients and from the sibling dashboard tools getDashboardMostActiveSwitches and getDashboardMostActiveEaps, though it never names those alternatives explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'This is a dashboard endpoint that provides a quick overview' implies the use case is a summarized view rather than exhaustive enumeration, which implicitly points away from listClients. There is no explicit when-to-use or when-not statement and no named alternative, so the routing guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listOsgAclsARead-only
List gateway (OSG) ACL rules for a site: firewall rules controlling traffic between WAN, LAN, and guest networks. Returns rule name, action (allow/deny), source/destination, protocol, and enabled state.
| 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. |
TDQS
A3.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint/destructiveHint already supplied, the description still adds real value by enumerating the shape of the result: rule name, action (allow/deny), source/destination, protocol, and enabled state. That tells the agent the call is safe and what content it will get back without an output schema. It stops short of noting ordering, pagination, or empty-result 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?
Two sentences, zero filler, and the core action is front-loaded before the explanatory gloss. Every clause carries information the agent needs.
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 read-only single-parameter list tool with full schema coverage and annotations, the definition covers purpose, domain meaning, and returned fields, which is nearly everything an agent needs. Minor omissions are result ordering and how a missing/invalid site resolves, but nothing blocks a correct call.
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 single siteId parameter already documents its pattern, the OMADA_SITE_ID fallback, and the pointer to listSites. The description adds nothing about parameters, so the baseline 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 gives a specific verb and resource ('List gateway (OSG) ACL rules for a site') and then defines what those rules are ('firewall rules controlling traffic between WAN, LAN, and guest networks'). The '(OSG)' qualifier implicitly separates it from switch/EAP ACL siblings, but it never names or contrasts with getOsgCustomAclList, getOswAclList, or listEapAcls, which is the most likely source of a mis-selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use statement, no preconditions, and no routing to alternatives, despite three close siblings (getOsgCustomAclList, getOswAclList, listEapAcls) plus getAclConfigTypeSetting. The only usage signal is implicit: the definition of ACLs implies you call this to inspect firewall rules, which the agent must infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listPendingDevicesARead-only
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.
| 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. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds scoping context ('this site') and the return shape, but says nothing about whether unadopted devices are filtered by discovery window, pagination, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, purpose front-loaded. Minor redundancy: 'not yet adopted' and 'waiting to be provisioned' say the same thing, so the final sentence does not fully earn 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?
With no output schema, the description helpfully enumerates returned fields (device type, MAC, IP, model), which is exactly the kind of detail an agent needs. For a simple read-only one-parameter tool that is close to sufficient; only sibling differentiation is missing.
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 single siteId parameter has 100% schema coverage with a pattern and default-site fallback already documented, so the schema does the heavy lifting. The description's reference to 'this site' loosely reinforces site scoping but adds no new meaning.
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?
States a specific verb and resource ('List devices discovered on the network but not yet adopted into this site'), and the adoption status makes it distinguishable from the many other device tools. It stops short of naming the closest sibling (listDevices) as the alternative for already-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?
The phrase 'devices waiting to be provisioned' implies the use case (pre-adoption onboarding checks), but there is no explicit when-to-use vs. when-not guidance and no routing to listDevices or searchDevices for the adopted-device case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listSitesApsPortsCRead-only
List ports on an AP.
| Name | Required | Description | Default |
|---|---|---|---|
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered, but the description adds essentially nothing beyond that bar: no indication of what a port record contains, whether results are paginated, or whether the AP must be online/connected for data to be returned. It largely restates 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity borders on under-specification rather than true conciseness, which is penalized in the other dimensions rather than here.
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 is low-complexity, has only two fully documented parameters, and carries annotations covering its safety profile, so the description is minimally sufficient to call it correctly. It still leaves gaps about what port data is returned and any preconditions (e.g., AP reachability), which matters given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both apMac (format plus a pointer to listDevices) and siteId (default-site fallback to OMADA_SITE_ID plus a pointer to listSites) fully documented in the schema. The description contributes no additional parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('List') and resource ('ports on an AP'), so an agent immediately knows this is a read of physical/logical port data for a given access point. It does not, however, distinguish it from port-oriented siblings such as getSwitchPorts or getStackPorts, nor clarify what 'ports' means for an AP (Ethernet uplinks vs. LAN ports).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance, and no alternative tool is named. The only routing hints ('Use listDevices to find AP MACs', 'Use listSites to discover site IDs') live in the schema parameter descriptions, not the tool description, and they concern parameter sourcing rather than tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listSitesCableTestSwitchesIncrementResultsBRead-only
Get cable test incremental results for a switch.
| 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. | |
| 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?
Annotations already declare this is a read-only, non-destructive operation. The description adds only the ambiguous term 'incremental' without explaining what incremental means, whether it returns a delta or paginated data, or any rate-limit/auth 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?
The description is a single front-loaded sentence with no filler. Every word contributes to identifying the operation, though the brevity leaves gaps handled elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity two-parameter read tool, the schema and annotations cover most invocation needs. However, the description never clarifies the relationship to full-results siblings or what 'incremental' returns, leaving a meaningful gap for an agent choosing among cable-test tools.
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 switchMac and siteId are fully documented in the schema, including cross-references to listDevices and listSites. The description adds no meaning beyond the schema, which is acceptable at baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: get cable test incremental results for a switch. It distinguishes the result type as 'incremental,' but does not explicitly differentiate from siblings like getCableTestFullResults or getCableTestLogs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus getCableTestFullResults or getCableTestLogs. It also omits any prerequisites or conditions for requesting incremental rather than full results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listSitesCableTestSwitchesPortsCRead-only
List ports available for cable test on a switch.
| 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. | |
| 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?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: no note about whether the switch must support cable test, whether an empty list is possible, or how results relate to getCableTestFullResults, making it essentially a restatement of 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the resource and constraint front-loaded and zero wasted words. Its brevity is efficient, though it borders on under-specification for a tool embedded in a multi-step cable-test workflow.
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 is simple (two params, full schema coverage, read-only annotations, no output schema), so the minimal description is not crippling. However, it omits the workflow context that would let an agent know why and when to call it before getCableTestFullResults or getCableTestLogs, leaving the definition only minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains siteId defaulting to OMADA_SITE_ID and the switchMac MAC format with discovery hints. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('List ports available for cable test on a switch'), which is clear and distinct from siblings like getCableTestLogs or getCableTestFullResults. It stops short of naming any sibling or stating scope boundaries, so the differentiation is implicit rather than explicit.
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 when-to-use guidance is given: the description never says this is the prerequisite step before running a cable test on a switch port, nor does it distinguish itself from the other cable-test tools in the sibling list. The agent must infer the workflow position from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listSitesStacksBRead-only
List switch stacks in a site.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — no mention of pagination behavior, empty-site behavior, or what a returned stack record contains — so it contributes almost nothing the agent could not infer.
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 short, front-loaded sentence with zero filler or redundancy. Nothing could be removed without losing the stated purpose.
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?
This is a simple read-only list tool with all three parameters documented in the schema and no output schema, so the description is minimally sufficient. It is still thin: it does not clarify what a 'switch stack' entity is or how results relate to the stack-detail sibling, which an agent selecting among 80+ switch tools would benefit from.
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%: page, pageSize ranges and the siteId default/pattern are all fully documented in the schema. The description adds no additional meaning about these parameters, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource (list switch stacks) and scopes it to a site, so an agent can tell it is a collection-listing call. It does not distinguish itself from close siblings such as getSwitchStackDetail, getOswStackLagList, or getStackNetworkList, which is the only thing keeping it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance at all: nothing says to call this to enumerate stacks versus getSwitchStackDetail to drill into one, and no prerequisite or pagination context is given. The schema does mention listSites for discovering site IDs, but that is a schema note, not description guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listSwitchNetworksARead-only
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| siteId | No | Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and destructiveHint annotations already establish the safe read-only behavior. Beyond that, the description adds useful output context by saying the result shows which VLANs are assigned to which ports, including tagged and untagged configurations. It does not discuss pagination or default-site behavior, but those are covered by 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no redundant wording. It front-loads the core purpose and follows with output details and the prerequisite lookup tool.
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 read-only list tool with full schema coverage and annotations, the description is largely complete: it states the purpose, summarizes return content, and points to listDevices for the required MAC. It could be slightly stronger by clarifying pagination or how this differs from adjacent switch-detail tools.
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 switchMac, siteId, page, and pageSize in detail. The description only repeats the switchMac guidance already present in the schema and adds no further meaning for the pagination or site parameters. This meets the baseline for high schema 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 states a specific verb and resource: listing VLAN network assignments for a switch, and it clarifies the returned content includes port-level tagged and untagged configurations. It does not explicitly distinguish this tool from related switch detail or stack network tools, so it falls short of 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage context by explaining that the tool lists VLAN-to-port assignments and that listDevices should be used to obtain switchMac values. It does not name when-not-to-use conditions or alternative tools for overlapping switch information, but the primary prerequisite is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listUpgradeFirmwaresBRead-only
List uploaded firmware files available for manual upgrade.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description usefully discloses that only *uploaded* firmware eligible for manual upgrade is returned, but it says nothing about result format, ordering, or whether pagination metadata is returned despite exposing page/pageSize.
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?
A single short sentence with the scope qualifier front-loaded and no filler. It is efficient, though its brevity is partly the reason other gaps (pagination, differentiation) exist rather than a sign of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter, read-only list tool with full schema coverage and annotations, the description covers the essentials. It falls short on how results relate to the sibling firmware tools and on any hint about pagination or volume, which matters at pageSize up to 1000.
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 page and pageSize both documented (defaults, ranges) in the schema itself. The description adds no syntax, default, or filtering semantics beyond what the schema already provides, so the baseline 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 uses a specific verb ('List') plus a qualified resource ('uploaded firmware files available for manual upgrade'), which is much clearer than the bare name. It does not, however, distinguish itself from the similarly named sibling 'listUpgradeOverviewFirmwares' or from 'getFirmwareInfo', so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'available for manual upgrade' implies the usage context (choosing a firmware image to push manually), but there is no explicit when-to-use, when-not-to-use, or named alternative. The reader must infer that this is the source list feeding a manual upgrade action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listUpgradeOverviewFirmwaresCRead-only
List firmware pool entries in the upgrade overview.
| Name | Required | Description | Default |
|---|---|---|---|
| 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description adds almost nothing: it doesn't say whether results are site-scoped or org-wide, how pagination totals behave, or what an entry contains, leaving the agent to infer behavior from the name alone.
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?
A single front-loaded sentence with no redundant wording — the resource and its scope come first. It is efficient, though its terseness borders on under-specification rather than exemplary 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?
For a simple two-parameter paginated list tool with annotations and no output schema, the essentials are present and the schema documents paging. Still missing is any signal about the result set's scope (which sites, which firmware pool) or how it differs from the closely named sibling list 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% and both parameters (page, pageSize) have descriptions with defaults and bounds, so the description adds no parameter meaning of its own. Baseline 3 is appropriate when the schema carries the full burden.
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 states a specific verb ('List') and resource ('firmware pool entries') scoped to the 'upgrade overview', so the agent knows exactly what is returned. It does not, however, differentiate this from the near-identical sibling listUpgradeFirmwares, which an agent could easily confuse it with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of prerequisites, and no pointer to alternatives. With siblings such as listUpgradeFirmwares, getUpgradeOverviewCritical, and getUpgradeOverviewTryBeta in the same family, the absence of routing guidance is a real gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchDevicesBRead-only
Search for devices globally across all sites the user has access to. Returns devices matching the search key.
| Name | Required | Description | Default |
|---|---|---|---|
| searchKey | Yes |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful permission scoping ('all sites the user has access to'), but says nothing about result caps, pagination, or whether matching is substring or exact — meaningful gaps for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, and the scope constraint is stated before the return behavior. It is arguably slightly too terse given the unexplained parameter, but nothing 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?
The tool is structurally simple (one required string, flat schema, no output schema to explain), but the one thing an agent must know — what to put in searchKey — is absent from both schema and description. Adequate on scope, incomplete on invocation.
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 single required parameter has 0% schema description coverage, so the description carries the full burden and does not meet it. It never says what searchKey matches (device name, MAC, serial, model) or whether matching is exact or case-insensitive partial.
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 gives a specific verb and resource ('Search for devices') plus a scope qualifier ('globally across all sites the user has access to'). This implicitly separates it from the site-scoped sibling getAllDeviceBySite and from listDevices, though neither is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'globally across all sites' implies the right context for use, but no alternative tool is named and no when-not-to-use condition is stated. An agent must infer that listDevices/getAllDeviceBySite are the narrower options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchOperationsARead-only
Search only enabled, implemented Omada tools. Results do not expand permissions. Inspect a result with describeOperation.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No |
TDQS
A3.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only safety profile, so the description's real contribution is the disclosure that only enabled and implemented tools surface and that results do not expand permissions. That permission-boundary note is meaningful behavioral context an agent could otherwise get wrong. It does not describe result shape or ordering, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each doing distinct work: scope, permission semantics, and next step. No filler and the scope constraint is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description says nothing about what a result looks like, how matches are ranked, or whether results are truncated by the limit. For a discovery tool whose output feeds describeOperation, that leaves a real gap, though the permission and follow-up notes cover the riskiest parts.
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?
Both parameters have 0% schema description coverage, so the description carries the full burden of explaining them and it does not mention query or limit at all. An agent must guess that query is a free-text match string and that limit caps result count.
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 a specific verb and resource (search Omada tools) and narrows the scope to enabled, implemented ones, which distinguishes it from the many concrete get/list siblings. It does not fully explain what an 'operation' record contains, but the intent is 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?
It gives an implied discovery workflow by naming describeOperation as the follow-up step for inspecting a result. It never says when to search instead of calling a known sibling tool directly, or what to do when a search returns nothing.
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.
113 tool updates
v0.19.0-rc.1- First observed
describeOperation - First observed
diagnoseCameraConnectivity - First observed
diagnoseClient - First observed
getAclConfigTypeSetting - First observed
getAllDeviceBySite - First observed
getApDetail - First observed
getApGeneralConfig - First observed
getApIpv6Config - First observed
getApLldpConfig - First observed
getAppControlCategories - First observed
getAppControlRules - First observed
getApplicationControlStatus - First observed
getApQosConfig - First observed
getApRadios - First observed
getApSnmpConfig - First observed
getApUplinkConfig - First observed
getApVlanConfig - First observed
getAttackDefenseSetting - First observed
getBandwidthCtrlDetail - First observed
getCableTestFullResults - First observed
getCableTestLogs - 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
getDeviceTagList - First observed
getDot1xConfig - First observed
getDownlinkWiredDevices - First observed
getFirewallSetting - First observed
getFirmwareInfo - First observed
getFirmwareUpgradePlan - First observed
getGatewayDetail - First observed
getGatewayHealth - First observed
getGatewayLanStatus - First observed
getGatewayPorts - First observed
getGatewayQosClassRules - First observed
getGatewayWanStatus - First observed
getGridAllowList - First observed
getGridAutoCheckUpgrade - First observed
getGridBlockList - First observed
getGridClientHistory - First observed
getGridEapRule - First observed
getGridGatewayRule - First observed
getGridKnownClients - First observed
getIspLoad - First observed
getMacFilterDetail - First observed
getMeshStatistics - First observed
getNetworkHealthSummary - First observed
getOsgCustomAclList - First observed
getOswAclList - First observed
getOswStackLagList - First observed
getPastClientNum - First observed
getQosPolicy - First observed
getRadiosConfig - First observed
getRadiusProxyConfig - First observed
getServerCapabilities - 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
getTrafficPriority - First observed
getUpgradeLogs - First observed
getUpgradeOverviewCritical - First observed
getUpgradeOverviewTryBeta - First observed
getUplinkWiredDetail - First observed
getUrlFilterBlacklist - First observed
getUrlFilterGeneral - First observed
getUrlFilterRules - First observed
getUrlFilterWhitelist - First observed
listClients - First observed
listClientsActivity - First observed
listClientsPastConnections - First observed
listDevices - First observed
listDevicesStats - First observed
listEapAcls - First observed
listMostActiveClients - First observed
listOsgAcls - 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 - First observed
searchOperations
TDQS
C2.7/5.0
Scored across 113 tools
Disambiguation2/5
Many tools have overlapping purposes: listDevices, getAllDeviceBySite, listDevicesStats, and searchDevices all return device inventories; getGatewayWanStatus, getGatewayLanStatus, and getGatewayPorts overlap heavily; cable-test tools and numerous AP config getters are hard to distinguish without reading full descriptions. Composite tools like getNetworkHealthSummary and getGatewayHealth help, but the set still presents multiple plausible choices for the same question.
Naming Consistency3/5
All names are camelCase, but conventions vary: getApDetail vs getSitesApsIpSetting vs getGridClientHistory vs listSitesCableTestSwitchesPorts mix resource-first and path-derived naming. Verbs are mostly get/list/search/diagnose, though the same resource can be addressed through different prefixes, making the pattern only partially predictable.
Tool Count1/5
113 tools is an extreme mismatch for a coherent MCP surface. The set is a broad mirror of controller endpoints rather than a curated set of operations, and many near-duplicate read endpoints make it difficult for an agent to choose correctly.
Completeness2/5
Coverage is heavily read-only: there are extensive getters for devices, clients, APs, switches, gateways, and firewall settings, but almost no create/update/delete operations for core lifecycle tasks such as adopting devices, upgrading firmware, configuring SSIDs, or editing ACLs. The searchOperations/describeOperation pair helps discovery but does not fill the missing mutation surface.
Maintenance
ActivityMaintained
ResponsivenessSyncing
Related MCP Connectors
Trust signals for AI agents: an open agent-readiness standard and developer tool guide. Read-only.
Context and control for any AI. Agent identity, scoped access, and proof across tools.
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Zero-trust gateway for AI agents: score tool calls, verify agent cards, enforce policy, audit.
Related MCP Servers
- AlicenseCqualityDmaintenanceExposes TP-Link Omada controller APIs to AI copilots, enabling listing of sites, devices, and clients, and executing arbitrary Omada API calls via natural language.8429MIT
- AlicenseAqualityCmaintenanceLets an AI assistant inspect and adjust TP-Link Omada WiFi networks by searching, describing, and calling any of roughly 1,650 Omada Open API operations through nine tools. It is read-only by default, refusing every non-GET request unless writes are explicitly unlocked, and even then returning a dry-run preview until a change is confirmed.94MIT
- AlicenseAqualityAmaintenanceEnables MCP-aware agents to query and manage a TP-Link Omada SDN controller by searching, inspecting, and calling operations from its live OpenAPI catalog.71MIT