BatterySnap

Battery stats by region

region_summary

Read-onlyIdempotent

Compare battery behaviour across regions in one call: one entry per continent or per country, each with the same mean / median / p25 / p75 / min / max blocks as fleet_summary (temperature, level, discharge and charge hours, awake ratio). Narrow with brand / model (e.g. how one model fares per continent) or with continent (e.g. group_by='country' within 'Africa').

The region is derived from the time zone the phone is set to (not GPS / IP), so travellers and manual settings blur it. Regions with fewer than 5 devices are left out and only counted (suppressed_*), as are devices whose time zone names no place (unlocated_device_count); check each group's device_count before comparing — small groups are noisy.

Input Schema

Name	Required	Description	Default
`brand`	No	Optional lowercase brand filter.
`model`	No	Optional model filter — matches resolved street name or raw Build.MODEL, case-insensitive.
`country`	No	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.
`group_by`	No	'continent' (default) or 'country' (ISO 3166 alpha-2).	continent
`continent`	No	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.

Output Schema

Name	Required	Description
`scope`	No	'fleet', or the comma-joined filters applied (e.g. 'brand:samsung,continent:Europe').
`groups`	No	One entry per region with enough devices, most devices first.
`group_by`	No	'continent' or 'country'.
`min_devices_per_group`	No	Groups with fewer devices than this are left out of `groups` and only counted below.
`suppressed_group_count`	No	Regions left out for having too few devices.
`unlocated_device_count`	No	Devices whose time zone names no place (UTC, GMT, unset): in no group, only counted here.
`suppressed_device_count`	No	Devices in those left-out regions.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedNov 2, 2026

removedOutput schema / properties / groups / items / properties / continent / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

changedOutput schema / properties / groups / items / properties / continent / description

Previous value: -"Continent of this group (group_by='continent'). Null for devices whose time zone names no place (UTC, GMT, unset)."New value: +"Continent of this group (group_by='continent')."

addedOutput schema / properties / groups / items / properties / continent / type
```
Added value: +"string"
```

removedOutput schema / properties / groups / items / properties / country / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

changedOutput schema / properties / groups / items / properties / country / description

Previous value: -"ISO 3166 alpha-2 country code of this group (group_by='country'). Null for devices whose time zone names no place."New value: +"ISO 3166 alpha-2 country code of this group (group_by='country')."

addedOutput schema / properties / groups / items / properties / country / type
```
Added value: +"string"
```

addedOutput schema / properties / unlocated_device_count

Added value: +{
+  "description": "Devices whose time zone names no place (UTC, GMT, unset): in no group, only counted here.",
+  "type": "integer"
+}

AddedNov 2, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Adds substantial context beyond the readOnly/idempotent annotations: the region is derived from the phone's time zone rather than GPS/IP, sub-5-device groups are suppressed and only counted in `suppressed_*`, and unparseable zones land in `unlocated_device_count`. It even warns that small groups are noisy and to check `device_count` before comparing — real interpretive guidance.

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?

Front-loaded with the purpose and the comparison primitive, then the semantics, then the caveats — a good information hierarchy. It runs slightly long with parenthetical asides, but every sentence carries usable information.

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?

An output schema exists, yet the description still flags the output fields that matter for correct interpretation (`device_count`, `suppressed_*`, `unlocated_device_count`). For a five-parameter, zero-required aggregation tool, nothing an agent needs in order to call or read it correctly is missing.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: filters compose intersectionally (brand/model within continent, continent plus country), and it shows a cross-parameter example (`group_by='country'` within 'Africa'). That explains how the filters interact rather than just restating them.

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?

Opens with a specific verb+resource+granularity: 'Compare battery behaviour across regions ... one entry per continent or per country', and names the exact stat blocks returned. It anchors itself to the sibling `fleet_summary` by saying the blocks are the same, so an agent can place it in the family immediately.

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?

Gives concrete usage patterns: narrow with `brand`/`model` ('how one model fares per continent') or `continent` combined with `group_by='country'`. It states the when-to-use clearly but names no explicit alternative or exclusion (e.g. pointing per-device questions to `device_summary`), so it stops short of a 5.

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?