BatterySnap

Return the mobile devices brands for which we have battery statistics, along with the number of distinct models, the number of devices recorded per brand, and the largest single-model device count within the brand (`max_devices_per_model`). Each entry also includes a `url` to the public BatterySnap web page for the brand (e.g. https://www.battery-snap.com/brands/samsung). Pass `min_device_count` / `max_device_count` and `min_model_count` / `max_model_count` to filter brands by recorded-device and distinct-model counts. Pass `fields` to keep only specific attributes in each entry. The full list is long: pass `limit` (and `offset` to page) unless you really need every brand, and prefer `search` when resolving one brand by name.

{
  "type": "object",
  "properties": {
    "min_device_count": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Drop entries with fewer than this many recorded devices. Defaults to 1 (keep all)."
    },
    "max_device_count": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Drop entries with more than this many recorded devices. Use to skip very common entries. Omit for no upper bound."
    },
    "min_model_count": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Drop brands with fewer than this many distinct models. Defaults to 0 (keep all)."
    },
    "max_model_count": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Drop brands with more than this many distinct models. Omit for no upper bound."
    },
    "limit": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Return at most this many entries. Omit for no cap — but the unbounded list can be very large, so prefer a limit."
    },
    "offset": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Skip this many entries before returning results — use with `limit` to page through a long list. Defaults to 0."
    },
    "fields": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional whitelist of attribute names to keep in each returned entry, used to shrink the response. When omitted or empty, all attributes documented in the output schema are returned. Unknown names are silently ignored."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "properties": {
          "brand": {
            "description": "Lowercase Android device brand identifier (e.g. 'samsung', 'xiaomi').",
            "type": "string"
          },
          "model_count": {
            "description": "Number of distinct device models recorded for this brand.",
            "type": "integer"
          },
          "device_count": {
            "description": "Number of individual devices of this brand that reported battery snapshots.",
            "type": "integer"
          },
          "max_devices_per_model": {
            "description": "Largest number of devices recorded for a single model within this brand (the most popular model's device count). 0 when the brand has no device with a known model.",
            "type": "integer"
          },
          "url": {
            "description": "Public BatterySnap web page listing this brand's models and devices. Locale-agnostic — the server 301-redirects to the visitor's detected locale.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}

Return the mobile devices models of the given brands for which we have battery statistics, along with the brand each model belongs to, the number of devices recorded, the average battery temperature in Celsius, and the min/max Android SDK level per model. Each entry is grouped by the resolved street name (e.g. 'Galaxy S23'), which may cover several raw Android Build.MODEL identifiers (carrier variants, regional SKUs, …). For URL building, every entry also exposes: * `raw_model_code`: a representative raw Build.MODEL identifier (the lexicographically smallest one among devices grouped under this street name), or null if no device reported a non-empty model code. * `url`: the public BatterySnap web page for the model, e.g. https://www.battery-snap.com/brands/samsung/models/SM-S911B. Built from `brand` + `raw_model_code`; null when either is null; `raw_model_code` is null. The page lists all devices reporting that exact raw model. Pass `min_device_count` / `max_device_count` to filter models by how many devices were recorded. For 'which models have the most devices' questions, pass sort='device_count' with a small `limit` (and typically fields=['brand', 'model', 'device_count', 'url']) instead of fetching and sorting the full list. Pass `fields` to keep only specific attributes in each entry. Omit `brands` (or pass an empty list) to return models across every brand.

{
  "type": "object",
  "properties": {
    "brands": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "One or more lowercase Android device brand identifiers (e.g. ['samsung', 'xiaomi']) to fetch models for. Matched case-insensitively. Omit (or pass an empty list) to return models across all brands."
    },
    "min_device_count": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Drop entries with fewer than this many recorded devices. Defaults to 1 (keep all)."
    },
    "max_device_count": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Drop entries with more than this many recorded devices. Use to skip very common entries. Omit for no upper bound."
    },
    "sort": {
      "default": "name",
      "description": "Sort order of the returned models: 'name' (default, alphabetical by brand then model) or 'device_count' (most recorded devices first). Combine sort='device_count' with `limit` to answer 'most popular models' questions in one small call.",
      "pattern": "^(name|device_count)$",
      "type": "string"
    },
    "limit": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Return at most this many models (applied after filtering and sorting). Omit for no cap."
    },
    "offset": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Skip this many entries before returning results — use with `limit` to page through a long list. Defaults to 0."
    },
    "fields": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional whitelist of attribute names to keep in each returned entry, used to shrink the response. When omitted or empty, all attributes documented in the output schema are returned. Unknown names are silently ignored."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "properties": {
          "brand": {
            "description": "Lowercase Android device brand identifier this model belongs to (e.g. 'samsung', 'xiaomi').",
            "type": "string"
          },
          "model": {
            "description": "Human-readable model name (e.g. 'Galaxy S23', 'Pixel 7a'). Resolved from the device's street_name column.",
            "type": "string"
          },
          "raw_model_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Representative raw Android Build.MODEL identifier (e.g. 'SM-S911B') for this model — the lexicographically smallest model code among all devices grouped under this street name. Multiple raw codes can map to one street name (e.g. carrier variants); this picks one as canonical for URL construction. Null when no device has a non-empty model code."
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Public BatterySnap web page for this model, e.g. https://www.battery-snap.com/brands/samsung/models/SM-S911B. Built from `brand` + `raw_model_code`; null when either is null. Locale-agnostic (server picks locale via redirect)."
          },
          "device_count": {
            "description": "Number of individual devices of this model that reported battery snapshots.",
            "type": "integer"
          },
          "avg_battery_temperature_celsius": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Average battery temperature in Celsius, weighted across all snapshots of all devices of this model. Null when no temperature samples were recorded."
          },
          "min_android_api_level": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Lowest Android API level reported by any device of this model (e.g. 28 = Android 9 Pie)."
          },
          "max_android_api_level": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Highest Android API level reported by any device of this model."
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}

Return the list of individual physical devices matching one or more (brand, model) pairs for which we have battery statistics. Each entry in the returned list describes ONE specific device (identified by its own `device_uid`) and the metrics on that entry are aggregates computed only from THAT device's own snapshot history — they are not aggregated across devices. Two devices of the same brand and model will appear as two separate entries with their own independent metrics. Per-device fields include: brand, resolved model (street name), raw Android model, snapshot count, activity window (first / last seen), average battery level, average / min / max battery temperature in Celsius, awake-ratio, discharge speed and AC / USB / wireless charge speed (hours per full 100% swing), Android SDK level, IANA time zone, and a `url` pointing at the public BatterySnap web page for the device's interactive battery history (https://www.battery-snap.com/device_history?device=<uid>). Each pair's model is matched case-insensitively against either the resolved street name (e.g. 'Galaxy S23') or the raw Android model identifier (e.g. 'SM-S911B'). Pass `fields` to keep only specific attributes per device and avoid bloated responses.

{
  "type": "object",
  "properties": {
    "pairs": {
      "description": "One or more {brand, model} pairs to look up. Each pair fetches devices matching that brand and model.",
      "items": {
        "properties": {
          "brand": {
            "description": "Lowercase Android device brand identifier (e.g. 'samsung', 'xiaomi'), matched case-insensitively against the device's brand.",
            "type": "string"
          },
          "model": {
            "description": "Model name matched case-insensitively against either the resolved street name (e.g. 'Galaxy S23') or the raw Android model identifier (e.g. 'SM-S911B').",
            "type": "string"
          }
        },
        "required": [
          "brand",
          "model"
        ],
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    },
    "fields": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional whitelist of attribute names to keep in each returned entry, used to shrink the response. When omitted or empty, all attributes documented in the output schema are returned. Unknown names are silently ignored."
    }
  },
  "required": [
    "pairs"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "properties": {
          "brand": {
            "description": "Lowercase Android device brand identifier this device belongs to (e.g. 'samsung', 'xiaomi').",
            "type": "string"
          },
          "device_uid": {
            "description": "Stable UUID identifying this device across snapshots.",
            "type": "string"
          },
          "url": {
            "description": "Public BatterySnap web page showing this device's interactive battery history, e.g. https://www.battery-snap.com/device_history?device=<uid>. Locale-agnostic — server 301-redirects to the visitor's locale.",
            "type": "string"
          },
          "street_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Human-readable model name resolved for this device (e.g. 'Galaxy S23', 'Pixel 7a'). Null when the model could not be resolved from the raw Android identifiers."
          },
          "raw_model": {
            "description": "Raw Android model identifier reported by the device (e.g. 'SM-G960F'). This is the value the device sends in Build.MODEL.",
            "type": "string"
          },
          "snapshot_count": {
            "description": "Total number of battery snapshots recorded for this device. Higher values mean the per-device aggregates are based on more samples and are more reliable.",
            "type": "integer"
          },
          "first_seen": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of the earliest battery snapshot recorded for this device. Null if unknown."
          },
          "last_seen": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of the most recent battery snapshot recorded for this device. Null if unknown."
          },
          "avg_battery_level_percent": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Mean battery charge level across all snapshots, in percent (normally 0-100; may be outside that range for corrupted samples). Null if no level samples."
          },
          "avg_battery_temperature_celsius": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Mean battery temperature in Celsius, across all snapshots. Null if no temperature samples."
          },
          "min_battery_temperature_celsius": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Coldest battery temperature in Celsius observed across all snapshots for this device. Null if no temperature samples."
          },
          "max_battery_temperature_celsius": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Hottest battery temperature in Celsius observed across all snapshots for this device. Sustained high values are a battery-health concern. Null if no temperature samples."
          },
          "awake_time_fraction": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Fraction of observed time the device was awake / screen-on (normally between 0 and 1)."
          },
          "avg_discharge_hours_per_full_charge": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Average hours to discharge a full 100% while running on battery (e.g. 40 means the battery lasts ~40 h from full to empty at this device's usage). Higher is better battery life."
          },
          "avg_ac_charge_hours_per_full_charge": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Average hours to charge a full 100% on an AC wall charger. Lower is faster."
          },
          "avg_usb_charge_hours_per_full_charge": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Average hours to charge a full 100% over USB (e.g. a computer port). Typically slower than AC."
          },
          "avg_wireless_charge_hours_per_full_charge": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Average hours to charge a full 100% wirelessly. Null if the device never charged wirelessly."
          },
          "android_api_level": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Android SDK API level reported by the device (e.g. 28 = Pie, 34 = Android 14)."
          },
          "time_zone": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "IANA time zone identifier reported by the device (e.g. 'Europe/Paris', 'America/New_York'). Indicates the geographic region the device is operating in. Null when unknown."
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}

Return aggregated battery metrics for ONE specific device: average / min / max temperature, average battery level, mean charge time per power source (AC, USB, wireless) and mean discharge time over a recent (~2 weeks) and a long (~2 months) window, plus awake ratio and basic device info. Also includes `url`: the public BatterySnap web page for this device's interactive battery history (https://www.battery-snap.com/device_history?device=<uid>). All values are pre-computed from the device's full snapshot history — no raw timeseries is returned.

{
  "type": "object",
  "properties": {
    "device_uid": {
      "description": "Stable device UUID returned by the `devices` tool.",
      "type": "string"
    }
  },
  "required": [
    "device_uid"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "device_uid": {
      "description": "Stable UUID identifying this device.",
      "type": "string"
    },
    "url": {
      "description": "Public BatterySnap web page showing this device's interactive battery history, e.g. https://www.battery-snap.com/device_history?device=<uid>. Locale-agnostic.",
      "type": "string"
    },
    "brand": {
      "description": "Lowercase Android brand identifier.",
      "type": "string"
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Human-readable resolved model name (e.g. 'Galaxy S23')."
    },
    "raw_model": {
      "description": "Raw Build.MODEL string reported by the device.",
      "type": "string"
    },
    "snapshot_count": {
      "description": "Total snapshots recorded for this device.",
      "type": "integer"
    },
    "first_seen": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "ISO 8601 timestamp of the earliest snapshot."
    },
    "last_seen": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "ISO 8601 timestamp of the most recent snapshot."
    },
    "observed_days": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Span in days between first_seen and last_seen."
    },
    "avg_battery_level_pct": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Mean battery charge level across all snapshots (0-100)."
    },
    "avg_temperature_c": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Mean battery temperature in Celsius across all snapshots."
    },
    "min_temperature_c": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Coldest battery temperature in Celsius ever observed."
    },
    "max_temperature_c": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hottest battery temperature in Celsius ever observed. Sustained highs are a battery-health concern."
    },
    "mean_discharge_hours_recent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Average hours to discharge 100%% over the last ~2 weeks. Null when not enough data."
    },
    "mean_discharge_hours_long": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Average hours to discharge 100%% over the last ~2 months."
    },
    "mean_ac_charge_hours_recent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours to charge 100%% on AC (wall charger) over the last ~2 weeks."
    },
    "mean_ac_charge_hours_long": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours to charge 100%% on AC over the last ~2 months."
    },
    "mean_usb_charge_hours_recent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours to charge 100%% over USB (computer) over the last ~2 weeks."
    },
    "mean_usb_charge_hours_long": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours to charge 100%% over USB over the last ~2 months."
    },
    "mean_wireless_charge_hours_recent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours to charge 100%% wirelessly over the last ~2 weeks."
    },
    "mean_wireless_charge_hours_long": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours to charge 100%% wirelessly over the last ~2 months."
    },
    "awake_ratio": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Fraction of observed time the device was awake / screen-on (0..1)."
    },
    "android_api_level": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Android SDK level (e.g. 34 = Android 14)."
    },
    "time_zone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "IANA time zone reported by the device."
    }
  }
}

Aggregate battery metrics across ALL devices of a given brand+model. Returns mean / median / p25 / p75 / min / max for: temperature (C), battery level (%), discharge speed (hours per 100%%), AC / USB / wireless charge speed (hours per 100%%), and awake ratio. Use this to characterize how a model behaves in the field, or to compare a single device against its model average. Also includes: * `raw_model_code`: representative raw Android Build.MODEL identifier (smallest among devices grouped under this street name), or null if none recorded. * `url`: public BatterySnap web page for the model (https://www.battery-snap.com/brands/<brand>/models/<raw_model_code>); null when `raw_model_code` is null.

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "Lowercase Android brand identifier (e.g. 'samsung').",
      "type": "string"
    },
    "model": {
      "description": "Model name, matched against resolved street name (e.g. 'Galaxy S23') or raw Build.MODEL (e.g. 'SM-S911B').",
      "type": "string"
    }
  },
  "required": [
    "brand",
    "model"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "Lowercase Android brand identifier.",
      "type": "string"
    },
    "model": {
      "description": "Resolved model name.",
      "type": "string"
    },
    "raw_model_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Representative raw Android Build.MODEL identifier (e.g. 'SM-S911B') — the lexicographically smallest model code among devices grouped under this street name. Null when no device has a non-empty model code."
    },
    "url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Public BatterySnap web page for this model. Built from `raw_model_code`; null when `raw_model_code` is null. Locale-agnostic."
    },
    "device_count": {
      "description": "Distinct devices of this model that reported snapshots.",
      "type": "integer"
    },
    "snapshot_count": {
      "description": "Sum of snapshots across all devices of this model.",
      "type": "integer"
    },
    "temperature_c": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "battery_level_pct": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "discharge_hours": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "ac_charge_hours": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "usb_charge_hours": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "wireless_charge_hours": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "awake_ratio": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    }
  }
}

Live fleet-wide counters: total devices, models, snapshots, sessions, the running snapshot-ingest rate (snapshots/sec) and the timing of the last insert batch. Use this for one-shot 'how big is the dataset / how fast is it growing' questions. Unlike `fleet_summary`, no per-device aggregation is involved — these are raw running counts from the database.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "device_count": {
      "description": "Distinct devices that have ever reported a snapshot.",
      "type": "integer"
    },
    "model_count": {
      "description": "Distinct resolved models (street names) across the fleet.",
      "type": "integer"
    },
    "snapshot_count": {
      "description": "Total battery snapshots stored across all devices, taken from the running counter in the `globals` table.",
      "type": "integer"
    },
    "session_count": {
      "description": "Total reboot-bounded sessions recorded across all devices.",
      "type": "integer"
    },
    "snapshot_insert_rate": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Exponentially-smoothed snapshot-ingest rate, in snapshots per second."
    },
    "last_snapshot_insert_time": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "ISO 8601 timestamp of the most recent snapshot-batch insert."
    },
    "last_snapshot_insert_count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Number of snapshots in the most recent insert batch."
    }
  }
}

Aggregate battery metrics across the entire fleet, or across one brand when `brand` is provided. Returns mean / median / p25 / p75 / min / max for the same set of metrics as `model_summary`. Use this for fleet-wide baselines that a single device or model can be compared against.

{
  "type": "object",
  "properties": {
    "brand": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional lowercase brand identifier. If set, aggregates across that brand only; otherwise across the entire fleet."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "scope": {
      "description": "'fleet' for whole fleet, or 'brand:<lowercase-brand>' when scoped to a brand.",
      "type": "string"
    },
    "device_count": {
      "description": "Distinct devices in scope.",
      "type": "integer"
    },
    "model_count": {
      "description": "Distinct resolved models in scope.",
      "type": "integer"
    },
    "snapshot_count": {
      "description": "Sum of snapshots across all devices in scope.",
      "type": "integer"
    },
    "temperature_c": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "battery_level_pct": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "discharge_hours": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "ac_charge_hours": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "usb_charge_hours": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "wireless_charge_hours": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "awake_ratio": {
      "properties": {
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Arithmetic mean across devices that reported this metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "50th percentile (p50) across devices."
        },
        "p25": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "25th percentile across devices."
        },
        "p75": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "75th percentile across devices."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest per-device value observed."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest per-device value observed."
        },
        "n": {
          "description": "Number of devices contributing a non-null value to this stat.",
          "type": "integer"
        }
      },
      "type": "object"
    }
  }
}

Return the devices with the longest single uptime ever recorded between reboots (max_elapsed_time). Optionally filter by brand and/or model. Useful to find which physical phones in the fleet are champions of staying powered on for weeks/months at a time. Each entry includes a `device_uid` you can feed into `device_summary` for deeper analysis, and a `url` pointing at the device's interactive battery history page on https://www.battery-snap.com.

{
  "type": "object",
  "properties": {
    "brand": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional lowercase brand filter. When omitted, devices from any brand are ranked together."
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional model filter — matches resolved street name or raw Build.MODEL, case-insensitive. When omitted, no model filter applies."
    },
    "limit": {
      "default": 10,
      "description": "Number of devices to return, 1..100.",
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "properties": {
          "brand": {
            "description": "Lowercase Android brand identifier.",
            "type": "string"
          },
          "device_uid": {
            "description": "Stable UUID identifying this device.",
            "type": "string"
          },
          "url": {
            "description": "Public BatterySnap web page showing this device's interactive battery history, e.g. https://www.battery-snap.com/device_history?device=<uid>. Locale-agnostic.",
            "type": "string"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Resolved model name (street name), e.g. 'Galaxy S23'."
          },
          "raw_model": {
            "description": "Raw Build.MODEL identifier reported by the device.",
            "type": "string"
          },
          "max_uptime_seconds": {
            "description": "Longest single uptime ever recorded between reboots, in seconds.",
            "type": "integer"
          },
          "max_uptime_hours": {
            "description": "Same value as max_uptime_seconds, in hours.",
            "type": "number"
          },
          "is_live": {
            "description": "True when the device has not yet rebooted past this max — the uptime is still climbing live.",
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}

Same as `top_devices_by_uptime`, but restricted to devices that have not yet rebooted past their recorded maximum — meaning the uptime is currently still climbing. These are the devices that are 'live' champions right now, as opposed to historical record-holders. Each entry includes a `url` pointing at the device's interactive battery history page on https://www.battery-snap.com.

{
  "type": "object",
  "properties": {
    "brand": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional lowercase brand filter. When omitted, devices from any brand are ranked together."
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional model filter — matches resolved street name or raw Build.MODEL, case-insensitive. When omitted, no model filter applies."
    },
    "limit": {
      "default": 10,
      "description": "Number of devices to return, 1..100.",
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "properties": {
          "brand": {
            "description": "Lowercase Android brand identifier.",
            "type": "string"
          },
          "device_uid": {
            "description": "Stable UUID identifying this device.",
            "type": "string"
          },
          "url": {
            "description": "Public BatterySnap web page showing this device's interactive battery history, e.g. https://www.battery-snap.com/device_history?device=<uid>. Locale-agnostic.",
            "type": "string"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Resolved model name (street name), e.g. 'Galaxy S23'."
          },
          "raw_model": {
            "description": "Raw Build.MODEL identifier reported by the device.",
            "type": "string"
          },
          "max_uptime_seconds": {
            "description": "Longest single uptime ever recorded between reboots, in seconds.",
            "type": "integer"
          },
          "max_uptime_hours": {
            "description": "Same value as max_uptime_seconds, in hours.",
            "type": "number"
          },
          "is_live": {
            "description": "True when the device has not yet rebooted past this max — the uptime is still climbing live.",
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}

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.

{
  "type": "object",
  "properties": {
    "metric": {
      "description": "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).",
      "type": "string"
    },
    "order": {
      "default": "desc",
      "description": "'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.",
      "pattern": "^(asc|desc)$",
      "type": "string"
    },
    "brand": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional lowercase brand filter. When omitted, devices from any brand are ranked together."
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional model filter — matches resolved street name or raw Build.MODEL, case-insensitive. When omitted, no model filter applies."
    },
    "limit": {
      "default": 10,
      "description": "Number of devices to return, 1..100.",
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "min_snapshots": {
      "default": 100,
      "description": "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.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "metric"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "properties": {
          "brand": {
            "description": "Lowercase Android brand identifier.",
            "type": "string"
          },
          "device_uid": {
            "description": "Stable UUID identifying this device; feed it to `device_summary` or `device_ranking`.",
            "type": "string"
          },
          "url": {
            "description": "Public BatterySnap page with this device's interactive battery history.",
            "type": "string"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Resolved model name (street name), e.g. 'Galaxy S23'."
          },
          "raw_model": {
            "description": "Raw Build.MODEL identifier reported by the device.",
            "type": "string"
          },
          "value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "The requested metric's value for this device, in the unit documented for that metric."
          },
          "snapshot_count": {
            "description": "Snapshots behind this device's aggregate — low counts mean a noisy value.",
            "type": "integer"
          },
          "last_seen": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of the device's most recent snapshot."
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}

Rank device MODELS by any battery metric, aggregating across every device of that model. This is the tool for 'which phone model has the best battery life', 'which models charge fastest', 'which run hottest' — questions that would otherwise need one `model_summary` call per model. Ordering is by the per-model MEDIAN of the metric (outlier-resistant); the mean is returned alongside. Use `brand` to rank within one manufacturer and `min_devices` to require a minimum sample size.

{
  "type": "object",
  "properties": {
    "metric": {
      "description": "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).",
      "type": "string"
    },
    "order": {
      "default": "desc",
      "description": "'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.",
      "pattern": "^(asc|desc)$",
      "type": "string"
    },
    "brand": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional lowercase brand filter. When omitted, devices from any brand are ranked together."
    },
    "limit": {
      "default": 10,
      "description": "Number of devices to return, 1..100.",
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "min_devices": {
      "default": 3,
      "description": "Ignore models backed by fewer devices than this. Defaults to 3 so a single outlier phone cannot win a ranking. Raise it for more robust comparisons.",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "metric"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "properties": {
          "brand": {
            "description": "Lowercase Android brand identifier.",
            "type": "string"
          },
          "model": {
            "description": "Resolved model name (street name).",
            "type": "string"
          },
          "raw_model_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Representative raw Build.MODEL identifier for URL building."
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Public BatterySnap page for this model; null when raw_model_code is null."
          },
          "device_count": {
            "description": "Distinct devices of this model contributing a value.",
            "type": "integer"
          },
          "mean_value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Mean of the metric across the model's devices."
          },
          "median_value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Median of the metric across the model's devices — the value the ranking is ordered by, as it resists outliers."
          },
          "snapshot_count": {
            "description": "Total snapshots behind this model's devices.",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}

Answer 'is MY phone normal?' — rank one device's metric against other devices of the same model AND against the whole fleet, in one call. Returns the device's value, its 1-based rank, its percentile, and the cohort median / mean / min / max for both cohorts. Prefer this over fetching `device_summary` + `model_summary` and comparing by hand: it is a single call and gives the percentile directly. The model cohort is the meaningful one for 'is this device degraded'; the fleet cohort puts the model itself in context.

{
  "type": "object",
  "properties": {
    "device_uid": {
      "description": "Stable device UUID returned by `devices`, `top_devices` or the share flow.",
      "type": "string"
    },
    "metric": {
      "default": "discharge_hours",
      "description": "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).",
      "type": "string"
    }
  },
  "required": [
    "device_uid"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "device_uid": {
      "description": "The device that was ranked.",
      "type": "string"
    },
    "url": {
      "description": "Public BatterySnap page with this device's interactive battery history.",
      "type": "string"
    },
    "brand": {
      "description": "Lowercase Android brand identifier.",
      "type": "string"
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Resolved model name (street name)."
    },
    "raw_model": {
      "description": "Raw Build.MODEL identifier.",
      "type": "string"
    },
    "metric": {
      "description": "The metric that was ranked.",
      "type": "string"
    },
    "snapshot_count": {
      "description": "Snapshots behind this device's aggregate.",
      "type": "integer"
    },
    "value": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "This device's value for the metric."
    },
    "model_cohort": {
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "This device's value for the metric. Null when the device has no value recorded."
        },
        "cohort_size": {
          "description": "Number of devices in this cohort that have a value for the metric.",
          "type": "integer"
        },
        "rank": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "1-based rank of this device within the cohort, 1 = highest value. Null when the device has no value."
        },
        "percentile": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Fraction of the cohort scoring strictly BELOW this device (0..1). 0.9 means it is higher than 90% of the cohort — whether that is good or bad depends on the metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Cohort median — the fair 'typical' value to compare against."
        },
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Cohort arithmetic mean."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest value in the cohort."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest value in the cohort."
        }
      },
      "type": "object",
      "description": "Rank against other devices of the SAME brand + model — the fair like-for-like comparison."
    },
    "fleet": {
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "This device's value for the metric. Null when the device has no value recorded."
        },
        "cohort_size": {
          "description": "Number of devices in this cohort that have a value for the metric.",
          "type": "integer"
        },
        "rank": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "1-based rank of this device within the cohort, 1 = highest value. Null when the device has no value."
        },
        "percentile": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Fraction of the cohort scoring strictly BELOW this device (0..1). 0.9 means it is higher than 90% of the cohort — whether that is good or bad depends on the metric."
        },
        "median": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Cohort median — the fair 'typical' value to compare against."
        },
        "mean": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Cohort arithmetic mean."
        },
        "min": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest value in the cohort."
        },
        "max": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest value in the cohort."
        }
      },
      "type": "object",
      "description": "Rank against every device in the fleet, all models mixed."
    }
  }
}

Resolve free-form user text into the canonical brand / model identifiers the other tools expect. Meant for phones named in free text: the other tools match brands and models exactly, so a guessed spelling returns an empty list. Matching is substring-based and case-insensitive over brand, resolved model name and raw Build.MODEL, ranked by exact match then popularity.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free text: a brand ('samsug'), a model name ('pixel 8'), a raw Build.MODEL code ('SM-S911B'), or both ('samsung galaxy s23').",
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "default": 10,
      "description": "Maximum brand hits and model hits to return (each list is capped separately).",
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "query": {
      "description": "The query that was resolved.",
      "type": "string"
    },
    "brands": {
      "description": "Matching brands, best match first.",
      "items": {
        "properties": {
          "brand": {
            "description": "Canonical lowercase brand identifier to pass to the other tools.",
            "type": "string"
          },
          "device_count": {
            "description": "Devices recorded for this brand.",
            "type": "integer"
          },
          "url": {
            "description": "Public BatterySnap page for the brand.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "models": {
      "description": "Matching models, best match first.",
      "items": {
        "properties": {
          "brand": {
            "description": "Canonical lowercase brand identifier.",
            "type": "string"
          },
          "model": {
            "description": "Canonical resolved model name (street name) to pass to the other tools.",
            "type": "string"
          },
          "raw_model_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Representative raw Build.MODEL identifier."
          },
          "device_count": {
            "description": "Devices recorded for this model.",
            "type": "integer"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Public BatterySnap page for the model; null when raw_model_code is null."
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  }
}