endpoint_show
Show Port OS devices with their supported controls.
To show a device, always call this tool: the widget it opens is the device's UI, so never render a second card, map or controls for it; answer in a sentence or two.
Uses the same selection, expansion and pagination arguments as endpoint_query. A single matching device opens its full view with now playing, transport, volume and other controls; several matches open only a list of names to choose from, so pass one full endpoint ID (or a query matching one device) to control a device. Showing a device does not start live video or send a control command.
Pass primary to choose which card leads, one of the device's card ids (every result lists them as cardIds; an unknown id is rejected with the available ones). The device's usual card and every other card stay behind the details toggle. Examples: "what's the battery on the vacuum" -> primary battery; "turn the thermostat fan on" -> primary fan; "how open are the blinds" -> primary closure; "show me the camera on the roborock" -> primary camera. "where is my phone" or "show its location" -> primary location; "show the roborock's map" or "pick a room to clean" -> primary house-map. Every result already includes the cached readings of the cards it lists (cardIds), so you can answer without a second call; pass expand to choose different capabilities. primary refreshes that card's readings from the device, so the answer is current. Always state the value in words: a FRESH reading is current; a STALE reading is the last known value, so say it is last known and give its age.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional field-first filter. Omit it to load full context; filter only when the account is large. Each key is a field or a combinator, and all keys of one object must match: {"name": {"like": "living"}, "type": {"in": ["LIGHT", "SWITCH"]}}. Combinators: {"and": [query, ...]}, {"or": [query, ...]}, {"not": query}. Text operators: eq (exact), in (any of a list), like (case-insensitive substring), lt and gt (lexical order). List operators: has (contains the exact value), like (some value contains the substring, case-insensitive). Fields: id (text) full endpoint ID; name (text) endpoint name; type (text) effective endpoint type, including customer overrides, such as LIGHT, SWITCH, PLUG or ROBOT_VACUUM; manufacturer (text) manufacturer name; model (text) model name; ownerId (text, eq only at the top level) principal whose endpoints to list; defaults to the caller; interfaces (list) full capability interface namespaces; messages (list) full message IDs the endpoint accepts; controllableGroups (list) IDs of groups the endpoint can act on, such as rooms a vacuum can clean (needs group:read). | |
| expand | No | Select observations to add to each device result, for example ["power", "connectivity"] or ["battery"]. Use capability names or full namespaces declared by the device. This reads attributes; it does not send commands or broaden the device search. Short names use port1/systems/zero/capability-interfaces. endpoint_show already includes cached readings for the cards it lists; expand replaces that selection. | |
| primary | No | The card to lead with, one of the device's card ids (shown as cardIds in the result), for example battery, fan, closure, thermostat, camera or remote; house-map for a vacuum's map or room picking (never draw your own map). Needs endpointId. Every other card stays behind the details toggle. | |
| nextToken | No | Opaque cursor returned by a previous endpoint_query call. | |
| enablement | No | Filter by ENABLED (default), DISABLED, or * for both. This filter is preserved by pagination. | ENABLED |
| endpointId | No | Return one endpoint by its full Port OS identifier. Cannot be combined with other filters or pagination. Results advertise its declared command and outbound message IDs. | |
| maxResults | No | Maximum number of results (default 10, maximum 100). | |
| forceDeviceAttributeQuery | No | Read selected attributes from devices instead of cache. Requires nonempty expand. Failed reads remain unavailable. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||