Skip to main content
Glama

List plugs, lights and sensors

hive_list_smart_devices
Read-only

List Hive smart plugs, lights, and sensors with online status, power or brightness settings, open/closed state, and battery levels; filter by device kind or force a fresh reading.

Instructions

List Hive smart plugs (on or off, power use), lights (on or off, brightness, colour temperature) and sensors (window and door sensors open or closed, motion sensors), with online status and batteries.

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": "hive_list_smart_devices"
  }
}

Input Schema

NameRequiredDescriptionDefault
rawNoReturn Hive's full objects instead of compact summaries (much larger)
kindNoOnly plugs, lights or sensors (default all)
freshNoAsk Hive again instead of using a reading from the last few seconds (HIVE_CACHE_SECONDS)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.5.1

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 openWorldHint=false, so safety is covered by structured fields rather than prose. The description's real contribution is enumerating the returned payload (on/off, power draw, brightness, colour temperature, open/closed, online status, battery) which matters because there is no output schema. However, it says nothing about the caching behavior implied by the "fresh" parameter and idempotentHint=false, which is the one genuinely surprising trait of this call.

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 the verb front-loaded and the three device families listed in a parallel structure; every clause carries information about coverage or returned fields. It is dense but not padded, though the nested parentheticals make it slightly harder to scan than a short bulleted breakdown would be.

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 only three well-documented optional parameters, the description's main job is to say what comes back, and it does that per device kind, including ancillary fields like online status and battery. The remaining gap is operational — no note on caching semantics or auth failure — but for a read-only listing tool this is close to sufficient.

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

Parameters3/5

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

Schema description coverage is 100% and all three optional parameters (raw, kind, fresh) are documented in the schema, including the HIVE_CACHE_SECONDS reference for fresh and the enum for kind. The description adds no parameter-level meaning of its own — it neither warns about the size cost of raw nor explains the caching window. Baseline 3 applies when the schema carries the full parameter 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 opens with a specific verb ("List") and enumerates exactly which resources are covered — smart plugs, lights, and window/door and motion sensors — plus the state attributes returned for each. That enumeration implicitly scopes out TRVs, which have their own sibling (hive_list_trvs), but it never explicitly contrasts with hive_list_devices, so an agent must infer the boundary between the two.

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 guess this is the tool for reading current device state, and the per-kind attribute list hints at what each query answers. There is no explicit statement of when to prefer this over hive_list_devices or hive_list_trvs, and no mention of auth prerequisites despite the presence of hive_auth_status as a sibling.

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