BatterySnap

Rank devices by metric

top_devices

Read-onlyIdempotent

Rank INDIVIDUAL devices by any battery metric — the general-purpose leaderboard. Use it for 'which phones run hottest / last longest / charge fastest', optionally narrowed to one brand and/or model. Returns at most limit rows, so it answers superlative questions in a single small call instead of enumerating the fleet.

Ranking is over each device's own lifetime aggregate. Pair the metric with the right order: e.g. hottest = temperature_c + desc, fastest AC charging = ac_charge_hours + asc, best battery life = discharge_hours + desc. There is no region filter here: regional questions go to the aggregates (region_summary, top_models, fleet_summary).

Input Schema

Name	Required	Description	Default
`brand`	No	Optional lowercase brand filter. When omitted, devices from any brand are ranked together.
`limit`	No	Number of devices to return, 1..100.
`model`	No	Optional model filter — matches resolved street name or raw Build.MODEL, case-insensitive. When omitted, no model filter applies.
`order`	No	'desc' (default) ranks the highest values first, 'asc' the lowest. Pick the direction that matches the question: fastest charging is ac_charge_hours + asc; longest battery life is discharge_hours + desc.	desc
`metric`	Yes	Which battery metric to rank on. One of: 'temperature_c' (mean battery temperature, C), 'max_temperature_c' / 'min_temperature_c' (hottest / coldest ever seen, C), 'battery_level_pct' (mean charge level, 0-100), 'discharge_hours' (hours to drain a full 100% - HIGHER means longer battery life), 'ac_charge_hours' / 'usb_charge_hours' / 'wireless_charge_hours' (hours to charge a full 100% on that source - LOWER means faster charging), 'awake_ratio' (fraction of time awake / screen-on, 0..1), 'snapshot_count' (how much data the device contributed), 'uptime_hours' (longest single uptime between reboots).
`min_snapshots`	No	Ignore devices with fewer snapshots than this, rounded down to a power of ten. Defaults to 100, which filters out barely-sampled devices whose averages are meaningless. Lower it only when a query returns too few rows.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 6, 2026

changedInput schema / properties / min_snapshots / description

Previous value: -"Ignore devices with fewer snapshots than this. Defaults to 100, which filters out barely-sampled devices whose averages are meaningless. Lower it only when a query returns too few rows."New value: +"Ignore devices with fewer snapshots than this, rounded down to a power of ten. Defaults to 100, which filters out barely-sampled devices whose averages are meaningless. Lower it only when a query returns too few rows."

Changed1 schema field changedNov 6, 2026

removedOutput schema / properties / result / items / properties / last_seen

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "ISO 8601 timestamp of the device's most recent snapshot."
-}

Changed4 schema fields changedNov 2, 2026

removedInput schema / properties / continent

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Optional continent, case-insensitive: 'Africa', 'Antarctica', 'Asia', 'Europe', 'North America', 'Oceania' or 'South America'. Keeps only devices whose time zone lies there. Combine with `country` for an intersection."
-}

removedInput schema / properties / country

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Optional ISO 3166 alpha-2 country code (e.g. 'FR', 'IN', 'US'), case-insensitive. Keeps only devices whose time zone belongs to that country. The region comes from the phone's time-zone setting, not GPS / IP."
-}

removedOutput schema / properties / result / items / properties / continent

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Continent derived from the device's time zone: one of 'Africa', 'Antarctica', 'Asia', 'Europe', 'North America', 'Oceania', 'South America'. Null when unknown."
-}

removedOutput schema / properties / result / items / properties / country

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "ISO 3166 alpha-2 country code derived from the device's time zone (e.g. 'FR' for Europe/Paris). It is where the phone's clock is set, not a GPS / IP location. Null when the zone names no place (UTC, GMT) or is unknown."
-}

Changed4 schema fields changedNov 2, 2026

addedInput schema / properties / continent

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional continent, case-insensitive: 'Africa', 'Antarctica', 'Asia', 'Europe', 'North America', 'Oceania' or 'South America'. Keeps only devices whose time zone lies there. Combine with `country` for an intersection."
+}

addedInput schema / properties / country

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional ISO 3166 alpha-2 country code (e.g. 'FR', 'IN', 'US'), case-insensitive. Keeps only devices whose time zone belongs to that country. The region comes from the phone's time-zone setting, not GPS / IP."
+}

addedOutput schema / properties / result / items / properties / continent

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Continent derived from the device's time zone: one of 'Africa', 'Antarctica', 'Asia', 'Europe', 'North America', 'Oceania', 'South America'. Null when unknown."
+}

addedOutput schema / properties / result / items / properties / country

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "ISO 3166 alpha-2 country code derived from the device's time zone (e.g. 'FR' for Europe/Paris). It is where the phone's clock is set, not a GPS / IP location. Null when the zone names no place (UTC, GMT) or is unknown."
+}

First observedOct 16, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/closed-world, so safety is covered; the description adds genuinely non-obvious behavior: ranking is over each device's lifetime aggregate rather than a live window, output is capped at 'limit' rows, and brand/model filters are optional narrowing rather than required scope. It does not discuss how ties or devices with sparse data outside min_snapshots are surfaced, 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 tight paragraphs ordered by importance: what it does, how to pair metric with order, and what it does not do. No filler sentences and no repetition of schema content beyond the illustrative metric/order examples that aid recall.

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 six-parameter read tool with a full output schema, the description covers purpose, filter semantics, result capping, aggregation basis, and the explicit exclusion of regional queries. An agent can call this correctly without opening the schema.

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?

With 100% schema coverage the per-parameter definitions are already handled, so the description's contribution is cross-parameter: it pairs metric direction with order ('hottest = temperature_c + desc', 'fastest AC charging = ac_charge_hours + asc'), which the schema only states generically. It also signals that brand/model are optional narrowing. The min_snapshots tuning advice is left to 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 and resource ('Rank INDIVIDUAL devices by any battery metric') and immediately frames it as 'the general-purpose leaderboard', which separates it from model-level (top_models) and uptime-specific (top_devices_by_uptime, top_devices_by_live_uptime) siblings. The capitalized INDIVIDUAL makes the unit of ranking unambiguous.

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?

Gives concrete when-to-use examples ('which phones run hottest / last longest / charge fastest') and explicitly routes the excluded case elsewhere: 'There is no region filter here: regional questions go to the aggregates (region_summary, top_models, fleet_summary)'. Nothing about tool 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.

All BatterySnap tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?