list_devices
List devices, ONE PAGE at a time — YOUR OWN by default (owner-scoped to the calling account: the same reach the dashboard gives you), or the WHOLE fleet with all:true (devices:view operators only; re-verified server-side — for a non-operator all is rejected, never silently widened). PAGINATION (r...
This record as markdown: /tools/dev-busymate-busymate-devtools/list-devices.md
What list_devices does on Busymate DevTools
AI agents call list_devices to retrieve information from Busymate DevTools without modifying anything. It is typically the context-gathering step in research, monitoring, and reporting workflows, before the agent takes action elsewhere.
| Parameter | Type | Required | Description |
|---|---|---|---|
all | boolean | — | devices:view operators only — list EVERY device (the whole fleet) instead of just YOUR OWN. |
limit | number | — | Max devices per page (default 100, cap 500). The byte budget may return fewer — check has_more. |
order | string | — | "last_seen" (default) = most-recently-seen first, best for browsing. "uuid" = the immutable key — the ONLY ordering that guarantees a complete, skip-free enumer |
cursor | string | — | Resume token from the previous page's `next_cursor`. Must be used with the SAME order and scope it was issued for. |
fields | string | — | "slim" (default) = identity + status + PAC, null keys omitted. "full" adds model, os_version and the parent linkage (~2x bytes per row). |
max_bytes | number | — | Page byte budget for the devices array (default 24000, min 2000, max 60000). Lower it for a small tool-result window. |
owner_email | string | — | OPERATOR cross-user scope (devices:view required, re-verified in-handler fail-closed): list the devices owned by the account(s) whose email matches this substri |
Parameters from the server's own tool schema.
Why list_devices is rated Low
Even though list_devices only reads data, uncontrolled read access leaks sensitive information and racks up API costs: an agent caught in a retry loop can make thousands of calls a minute without anyone noticing.
Risk signalsBulk/mass operation — affects multiple targets
Attacks that exploit this kind of access
The rule that runs list_devices safely
PolicyLayer is an MCP gateway: it sits between your AI agents and Busymate DevTools, and checks every tool call against a rule you set before the call runs. Nothing changes on the server itself. For list_devices, this is the rule to start with:
list_devices is read-only, so it stays allowed. Everything else on the server is denied unless you say otherwise.
The button opens the PolicyLayer dashboard: create your workspace, connect Busymate DevTools, apply this rule, and every list_devices call is checked against it from then on.
Questions about list_devices
List devices, ONE PAGE at a time — YOUR OWN by default (owner-scoped to the calling account: the same reach the dashboard gives you), or the WHOLE fleet with all:true (devices:view operators only; re-verified server-side — for a non-operator all is rejected, never silently widened). PAGINATION (read this before concluding anything is absent): every response carries total (the EXACT count in scope), returned (rows in THIS page), has_more, and next_cursor. If has_more is true the answer is INCOMPLETE — call again with cursor: <next_cursor> (same order and same scope) and repeat until has_more is false. NEVER report that a device/port/name is absent from a page where has_more was true; page to the end or resolve it directly with get_device. truncated_by:"byte_budget" means the page stopped early to fit the response budget — the cut rows are simply the NEXT page, nothing was lost. ORDERING: order:"last_seen" (default) is recency-first and best for browsing, but last_seen_at moves whenever a device heartbeats, so a row can shift ahead of the cursor mid-run — for a GUARANTEED complete enumeration pass order:"uuid" (immutable key, stable_enumeration:true). Each row is a slim projection: uuid, name, platform, online (DERIVED from last_seen_at freshness — #776, never the raw device_status latch), last_seen_at, vpn_state, the per-device connection_type override (null = inherits user → global), and pac_port/pac_url for PAC-provisioned devices; null keys are omitted. fields:"full" adds model, os_version and parent_device_id + parent_name (farm/iOS children resolve their host's NAME) at ~2x the bytes per row. Fleet rows also resolve each owner to a human name. OPERATOR CROSS-USER: owner_email scopes the fleet to the account(s) whose email matches that substring (case-insensitive) — the dashboard /devices owner-email search's MCP twin; devices:view is required and re-verified in-handler, so for a non-operator owner_email is rejected exactly like all. Use to answer "what devices do I own" / "list my devices" / "which devices are online". BROWSING ONLY: to resolve a device you ALREADY have a uuid, name, or PAC port/URL for, call get_device with it directly — never scan or page this list hunting for a known device. Read-only, no confirm. Returns { ok, scope: own|fleet, order, stable_enumeration, returned, total, has_more, next_cursor, truncated_by, fields, devices:[…], note? }. It is categorised as a Read tool in the Busymate DevTools MCP Server, which means it retrieves data without modifying state.
list_devices accepts 7 parameters: all, limit, order, cursor, fields, max_bytes, owner_email. The full parameter table on this page comes from the server's own tool schema.
Register the Busymate DevTools MCP server in PolicyLayer and add a rule for list_devices: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches Busymate DevTools. Nothing to install.
list_devices is a Read tool with low risk. Read-only tools are generally safe to allow by default.
Yes. Add a rate_limit block to the list_devices rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.
Set action: deny in the PolicyLayer policy for list_devices. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.
list_devices is provided by the Busymate DevTools MCP server (https://mcp.busymate.dev). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.
More on Busymate DevTools, and thousands of servers like it.
This server
Across the catalogue