Skip to main content
Glama

List known clients

unifi_list_known_clients
Read-only

Lists all clients stored by a UniFi controller, online or offline, most recently seen first, including aliases, notes, fixed IPs, and block status for auditing and lookup.

Instructions

List every client the controller has stored, online or offline, most recently seen first, with alias, note, fixed IP and block status. For live connection details use unifi_list_clients or unifi_get_client.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "unifi_list_known_clients"
  }
}

Input Schema

NameRequiredDescriptionDefault
rawNoReturn the full controller objects (large)
siteNoSite name/ID as used in the API (e.g. 'default'). Defaults to the configured site. See unifi_list_sites.
limitNoMaximum items to return (default 200)
fieldsNoOnly return these fields per item (dot paths, e.g. uplink.name)
filterNoOnly blocked clients, clients with a fixed IP, clients with a note, or clients with an alias
searchNoCase-insensitive substring match on names, MACs, IPs and similar

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.9.1
    • addedInput schema / properties / fields / description
      Added value: +"Only return these fields per item (dot paths, e.g. uplink.name)"
    • changedInput schema / properties / limit / description
      Previous value: -"Default 200"New value: +"Maximum items to return (default 200)"
    • addedInput schema / properties / search / description
      Added value: +"Case-insensitive substring match on names, MACs, IPs and similar"
  2. First observedv0.8.1

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already cover read-only safety, so the description's added value is the ordering guarantee ("most recently seen first") and the inclusion of offline clients — both behavioral facts absent from the annotations. It does not discuss pagination or the default limit, but the schema covers that.

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 defining scope comes first and the sibling routing comes second, which is the right order for a reader deciding whether to keep reading.

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

Completeness4/5

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

With no output schema, the description usefully names the fields returned and the sort order, which is the main thing an agent cannot get from structured data. For a simple read-only list tool with fully documented parameters, this is close to sufficient; only pagination/limit default behavior is left to the schema.

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

Parameters3/5

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

Schema description coverage is 100%, so the six parameters (raw, site, limit, fields, filter, search) are already fully documented and the baseline is 3. The description's mention of alias, note, fixed IP and block status loosely maps onto the filter enum values but adds 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 and resource ("List every client the controller has stored") plus the scope that defines it: online or offline, sorted most-recently-seen first, with the notable stored fields (alias, note, fixed IP, block status). It explicitly separates this from unifi_list_clients and unifi_get_client, so an agent can pick correctly without opening 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?

"For live connection details use unifi_list_clients or unifi_get_client" gives a clear routing rule and a when-not-to-use condition. It stops short of explaining how to choose between those two alternatives, so the agent must still infer whether it wants a list or a single-client lookup.

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