Real-world Android battery stats from BatterySnap users: device, model and fleet rankings.
Scored across 13 tools
Most tools target clearly distinct resources (brands, models, devices, fleet) and the descriptions proactively steer selection (e.g. device_ranking over device_summary+model_summary). The main ambiguity is the cluster of ranking tools (top_devices, top_devices_by_uptime, top_devices_by_live_uptime, top_models) which overlap heavily in purpose, though descriptions do differentiate them.
Names are uniformly snake_case and readable, with a predictable resource/action feel (device_summary, model_summary, fleet_totals, top_models). However, several tools are bare nouns (brands, devices, models, search) while others use prefixes, so the verb_noun pattern is not strictly maintained.
13 tools is well-scoped for a battery-analytics domain, with each tool covering a distinct level of aggregation (device, model, brand, fleet) or a distinct query type. Nothing feels redundant or missing at the count level.
The read-only surface covers discovery (brands, models, search), per-entity metrics (device/model/fleet summaries), leaderboards, and fleet counters, which is strong lifecycle coverage for a query API. Minor gaps: no raw timeseries access and no explicit pagination/metadata tool, though limit/offset params mitigate this.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Return at most this many entries. Omit for no cap — but the unbounded list can be very large, so prefer a limit. | |
| fields | No | 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. | |
| offset | No | Skip this many entries before returning results — use with `limit` to page through a long list. Defaults to 0. | |
| max_model_count | No | Drop brands with more than this many distinct models. Omit for no upper bound. | |
| min_model_count | No | Drop brands with fewer than this many distinct models. Defaults to 0 (keep all). | |
| max_device_count | No | Drop entries with more than this many recorded devices. Use to skip very common entries. Omit for no upper bound. | |
| min_device_count | No | Drop entries with fewer than this many recorded devices. Defaults to 1 (keep all). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description still adds real behavioral context: the unbounded list 'can be very large' so a limit is preferred, and unknown `fields` names are silently ignored — neither is derivable from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with what is returned, then filters, then the performance warning — a sensible ordering with no filler. It is slightly long and restates some parameter behavior already documented in the 100%-covered schema, which costs it the top mark.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need no narration, and annotations carry the safety profile; the description fills the remaining gaps an agent needs — payload size, paging, filtering, and the alternative tool for a single brand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description goes beyond it by explaining the intent behind the parameters: min/max device and model counts filter the list, `fields` prunes entries, and limit/offset should be used proactively because of list size.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Return the mobile devices brands for which we have battery statistics') and enumerates the exact per-entry attributes returned, including `max_devices_per_model` and the brand `url`. An agent can distinguish this from siblings like `top_models` or `fleet_summary` without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent to pass `limit` (and `offset`) unless every brand is genuinely needed, and routes single-brand lookups to `search` by name. Both the when-to-use and the named alternative are stated directly rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | No | 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). | discharge_hours |
| device_uid | Yes | Stable device UUID returned by `devices`, `top_devices` or the share flow. |
| Name | Required | Description |
|---|---|---|
| url | No | Public BatterySnap page with this device's interactive battery history. |
| brand | No | Lowercase Android brand identifier. |
| fleet | No | Rank against every device in the fleet, all models mixed. |
| model | No | Resolved model name (street name). |
| value | No | This device's value for the metric. |
| metric | No | The metric that was ranked. |
| raw_model | No | Raw Build.MODEL identifier. |
| device_uid | No | The device that was ranked. |
| model_cohort | No | Rank against other devices of the SAME brand + model — the fair like-for-like comparison. |
| snapshot_count | No | Snapshots behind this device's aggregate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered. The description adds interpretive behavior beyond that: it names the four return elements (value, 1-based rank, percentile, cohort stats) and, more usefully, explains what each cohort means. It stops short of anything about pagination or limits, but none is needed for a single-device lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the user question and the one-call promise before the mechanics, and each sentence carries signal (purpose, return shape, alternative, cohort interpretation). The 'Answer is MY phone normal?' hook and the two-cohort explanation make it slightly longer than strictly necessary, but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be fully specified, yet the description still summarizes them and adds the cohort-interpretation nuance. For a two-parameter read tool with full annotation coverage, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the metric parameter's exhaustive value list and semantics are already fully documented in the schema, and device_uid explains its provenance. The description adds no parameter-level detail beyond the schema, so the baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (rank) and resource (one device's metric) with the exact scope: against same-model devices AND the whole fleet in one call. It explicitly names the siblings it supersedes (device_summary + model_summary), so an agent can tell it apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use guidance: 'Prefer this over fetching device_summary + model_summary and comparing by hand.' It also disambiguates the two cohorts, saying the model cohort matters for 'is this device degraded' while the fleet cohort contextualizes the model.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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=).
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.
| Name | Required | Description | Default |
|---|---|---|---|
| pairs | Yes | One or more {brand, model} pairs to look up. Each pair fetches devices matching that brand and model. | |
| fields | No | 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe-read profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description adds genuine behavioral context beyond that: one entry per device with independently computed metrics, case-insensitive matching against either street name or raw model, and the response-shrinking role of `fields`. It stops short of any rate-limit or result-cap/pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and per-device semantics are front-loaded in the opening sentences, and the closing note on `fields` is actionable. The middle enumeration of per-device fields is somewhat redundant given an output schema exists, which is the main source of avoidable length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with full schema coverage, an output schema, and annotations covering safety, the description supplies everything else an agent needs: entity grain (one device per entry), aggregation semantics, matching rules across two identifier forms, and the `url` pattern. Nothing required to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both `pairs` and `fields` are already documented in the schema itself. The description restates the case-insensitive model-matching rule and the fields whitelist but adds no syntax or format detail the schema lacks; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Return the list of individual physical devices matching one or more (brand, model) pairs'. It sharply scopes the result as per-device rather than aggregated, which conceptually separates it from siblings like device_summary or model_summary, but it never names those siblings explicitly, so differentiation is inferential rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the per-device framing ('they are not aggregated across devices'), which hints this is the tool for individual-device data versus sibling aggregation tools. However, there is no explicit when-to-use/when-not guidance or named alternative, so the agent must infer routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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=). All values are pre-computed
from the device's full snapshot history — no raw timeseries is returned.
| Name | Required | Description | Default |
|---|---|---|---|
| device_uid | Yes | Stable device UUID returned by the `devices` tool. |
| Name | Required | Description |
|---|---|---|
| url | No | Public BatterySnap web page showing this device's interactive battery history, e.g. https://www.battery-snap.com/device_history?device=<uid>. Locale-agnostic. |
| brand | No | Lowercase Android brand identifier. |
| model | No | Human-readable resolved model name (e.g. 'Galaxy S23'). |
| last_seen | No | ISO 8601 timestamp of the most recent snapshot. |
| raw_model | No | Raw Build.MODEL string reported by the device. |
| time_zone | No | IANA time zone reported by the device. |
| device_uid | No | Stable UUID identifying this device. |
| first_seen | No | ISO 8601 timestamp of the earliest snapshot. |
| awake_ratio | No | Fraction of observed time the device was awake / screen-on (0..1). |
| observed_days | No | Span in days between first_seen and last_seen. |
| snapshot_count | No | Total snapshots recorded for this device. |
| android_api_level | No | Android SDK level (e.g. 34 = Android 14). |
| avg_temperature_c | No | Mean battery temperature in Celsius across all snapshots. |
| max_temperature_c | No | Hottest battery temperature in Celsius ever observed. Sustained highs are a battery-health concern. |
| min_temperature_c | No | Coldest battery temperature in Celsius ever observed. |
| avg_battery_level_pct | No | Mean battery charge level across all snapshots (0-100). |
| mean_ac_charge_hours_long | No | Hours to charge 100%% on AC over the last ~2 months. |
| mean_discharge_hours_long | No | Average hours to discharge 100%% over the last ~2 months. |
| mean_usb_charge_hours_long | No | Hours to charge 100%% over USB over the last ~2 months. |
| mean_ac_charge_hours_recent | No | Hours to charge 100%% on AC (wall charger) over the last ~2 weeks. |
| mean_discharge_hours_recent | No | Average hours to discharge 100%% over the last ~2 weeks. Null when not enough data. |
| mean_usb_charge_hours_recent | No | Hours to charge 100%% over USB (computer) over the last ~2 weeks. |
| mean_wireless_charge_hours_long | No | Hours to charge 100%% wirelessly over the last ~2 months. |
| mean_wireless_charge_hours_recent | No | Hours to charge 100%% wirelessly over the last ~2 weeks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered. The description adds meaningful behavioral context beyond that: values are pre-computed from full snapshot history, no raw timeseries is returned, and it defines the ~2 week and ~2 month windows and the included public `url`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb and scope, then efficiently enumerates the returned aggregates. The field listing is somewhat long for a tool that already has an output schema, but every clause adds genuine scoping or return-context information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Safety is covered by annotations and return structure by the output schema, and the description still usefully clarifies the pre-computed nature, window definitions, and non-return of raw timeseries. Only the sibling selection guidance remains implicit rather than explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains device_uid as the UUID returned by the `devices` tool. The description reinforces the single-device constraint but adds no format or syntax detail beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return aggregated battery metrics for ONE specific device') and enumerates the exact aggregates (temperature, battery level, charge/discharge times, awake ratio, device info). The all-caps 'ONE specific device' scope directly distinguishes it from fleet_summary and model_summary siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The single-device scope clearly contrasts with the fleet/model aggregation siblings, and the input schema points to the `devices` tool as the source of the uid, giving the agent a clear context for when to reach for this tool. It stops short of explicit when/when-not exclusions naming the alternative siblings directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Optional lowercase brand identifier. If set, aggregates across that brand only; otherwise across the entire fleet. |
| Name | Required | Description |
|---|---|---|
| scope | No | 'fleet' for whole fleet, or 'brand:<lowercase-brand>' when scoped to a brand. |
| awake_ratio | No | |
| model_count | No | Distinct resolved models in scope. |
| device_count | No | Distinct devices in scope. |
| temperature_c | No | |
| snapshot_count | No | Sum of snapshots across all devices in scope. |
| ac_charge_hours | No | |
| discharge_hours | No | |
| usb_charge_hours | No | |
| battery_level_pct | No | |
| wireless_charge_hours | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the safety profile is covered. The description's additional content (aggregation scope, statistic set) is largely duplicative of the `brand` schema description and the output schema, leaving little genuinely new behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences that lead with the aggregation scope and then the purpose; nothing is buried. The statistic enumeration (mean/median/p25/p75/min/max) is mildly redundant with the output schema but still reads efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-parameter read-only aggregation tool with an output schema and safety annotations already present, the description supplies all the framing an agent needs: what is aggregated, over what scope, and what the numbers are for.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single `brand` parameter is fully documented in the schema (optional, lowercase, aggregates that brand only). The description restates the same conditional behavior without adding format, casing, or fallback semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (aggregate) and resource (battery metrics) plus the exact scope (whole fleet, or one brand when `brand` is set), and explicitly ties itself to `model_summary` as the metric-set reference point. An agent can distinguish it from siblings like device_summary/fleet_totals without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this for fleet-wide baselines that a single device or model can be compared against" gives clear when-to-use context and implies the relationship to per-device/per-model tools. It stops short of naming the sibling alternatives (model_summary, device_summary) as explicit fallbacks, so it is strong but not routing-complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| model_count | No | Distinct resolved models (street names) across the fleet. |
| device_count | No | Distinct devices that have ever reported a snapshot. |
| session_count | No | Total reboot-bounded sessions recorded across all devices. |
| snapshot_count | No | Total battery snapshots stored across all devices, taken from the running counter in the `globals` table. |
| snapshot_insert_rate | No | Exponentially-smoothed snapshot-ingest rate, in snapshots per second. |
| last_snapshot_insert_time | No | ISO 8601 timestamp of the most recent snapshot-batch insert. |
| last_snapshot_insert_count | No | Number of snapshots in the most recent insert batch. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint=false and idempotentHint, so the safety profile is covered. The description still adds useful behavioral context beyond the schema: the counters are 'live' real-time running values and are 'raw' database counts rather than computed aggregations. It stops short of noting update cadence or whether numbers can lag, but that is a minor gap given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences: the returned counters come first, then the intended use case, then the sibling differentiation. Every clause carries information an agent needs for selection; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not enumerate return fields, and it does not waste words doing so. For a parameterless, read-only counter tool, purpose, usage, and sibling differentiation are all present — nothing required for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly avoids inventing filtering options that do not exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (fleet-wide counters) and enumerates exactly what is counted: devices, models, snapshots, sessions, ingest rate, and last insert batch timing. It explicitly contrasts itself with `fleet_summary`, so an agent can distinguish it from siblings without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Prescribes the exact use case ('one-shot how big is the dataset / how fast is it growing questions') and names the alternative (`fleet_summary`) with the discriminating condition (no per-device aggregation). This is explicit when-to-use plus alternatives, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | 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. | name |
| limit | No | Return at most this many models (applied after filtering and sorting). Omit for no cap. | |
| brands | No | 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. | |
| fields | No | 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. | |
| offset | No | Skip this many entries before returning results — use with `limit` to page through a long list. Defaults to 0. | |
| max_device_count | No | Drop entries with more than this many recorded devices. Use to skip very common entries. Omit for no upper bound. | |
| min_device_count | No | Drop entries with fewer than this many recorded devices. Defaults to 1 (keep all). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, closed-world), yet the description adds real behavioral context: entries are grouped by a resolved 'street name' that may aggregate several raw Build.MODEL identifiers, and null semantics for raw_model_code/url. The url sentence is garbled ('null when either is null; `raw_model_code` is null'), slightly muddying an otherwise strong disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and return shape, then structured bullets for raw_model_code/url and a short paragraph of filter guidance. Most sentences earn their place, though the url bullet is redundant with the output schema and contains a broken clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All seven optional parameters are documented in the schema and an output schema exists, so return values are covered. The description nonetheless supplies the grouping/aggregation nuance an agent needs, with only minor redundancy and the malformed url-explanation sentence as gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all seven parameters thoroughly. The description largely restates schema text (sort+limit combo, fields whitelist, brands omission), adding little semantics beyond it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the mobile device models of the given brands') and enumerates the exact attributes returned (device counts, avg battery temperature, min/max SDK level). It is clearly distinguishable from siblings like `brands`, `model_summary`, and `devices`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use guidance: pass min/max_device_count to filter, use sort='device_count' with a small limit for 'most devices' questions, use fields to shrink responses, and omit brands to span all brands. It stops short of naming sibling tools (e.g. `top_models`, `model_summary`) as explicit alternatives, so routing is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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//models/<raw_model_code>); null when
raw_model_code is null.
| Name | Required | Description | Default |
|---|---|---|---|
| brand | Yes | Lowercase Android brand identifier (e.g. 'samsung'). | |
| model | Yes | Model name, matched against resolved street name (e.g. 'Galaxy S23') or raw Build.MODEL (e.g. 'SM-S911B'). |
| Name | Required | Description |
|---|---|---|
| url | No | Public BatterySnap web page for this model. Built from `raw_model_code`; null when `raw_model_code` is null. Locale-agnostic. |
| brand | No | Lowercase Android brand identifier. |
| model | No | Resolved model name. |
| awake_ratio | No | |
| device_count | No | Distinct devices of this model that reported snapshots. |
| temperature_c | No | |
| raw_model_code | No | 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. |
| snapshot_count | No | Sum of snapshots across all devices of this model. |
| ac_charge_hours | No | |
| discharge_hours | No | |
| usb_charge_hours | No | |
| battery_level_pct | No | |
| wireless_charge_hours | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description goes beyond them by disclosing aggregation semantics (metrics computed over all devices of the brand+model), the exact statistics returned, and null semantics for raw_model_code and url — genuinely useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in the first sentence and the rest is organized into an enumerable metric list and two bullets. Slightly verbose — the enumerated statistics and the url/raw_model_code bullets duplicate information an output schema likely already carries — but nothing is wasted confusingly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param, read-only aggregation tool with full schema coverage and an output schema, the description covers scope, statistics computed, intended use, and edge cases (null raw_model_code/url). Nothing necessary for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both params are documented there (lowercase brand, model matched against street name or raw Build.MODEL). The description's 'brand+model' phrasing and mention of 'street name' groupings add only marginal clarity beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a precise verb+resource+scope: 'Aggregate battery metrics across ALL devices of a given brand+model.' The 'ALL devices' scope implicitly contrasts with sibling device_summary (single device), and the closing sentence about comparing a single device to its model average reinforces that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states intended uses: 'Use this to characterize how a model behaves in the field, or to compare a single device against its model average.' That is clear when-to-use context, but it does not name the alternatives (e.g. device_summary, models) or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum brand hits and model hits to return (each list is capped separately). | |
| query | Yes | Free text: a brand ('samsug'), a model name ('pixel 8'), a raw Build.MODEL code ('SM-S911B'), or both ('samsung galaxy s23'). |
| Name | Required | Description |
|---|---|---|
| query | No | The query that was resolved. |
| brands | No | Matching brands, best match first. |
| models | No | Matching models, best match first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuinely useful non-structured behavior: substring-based, case-insensitive matching over brand, resolved model name and raw Build.MODEL, ranked by exact match then popularity. It does not describe result handling when nothing matches, which is a minor residual gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose, then the rationale, then the matching algorithm in two tight paragraphs with no filler. Every sentence adds decision-relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values need not be explained. Purpose, when-to-use, alternative comparison and matching behavior are all present, making the definition complete for a 2-parameter resolver tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the matching semantics that govern how 'query' behaves (substring, case-insensitive, ranked by exactness then popularity). That meaningfully informs how an agent should phrase the query, beyond the schema's enumeration of input examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Resolve free-form user text into the canonical brand / model identifiers') and explicitly defines the tool's scope as fuzzy-name resolution. It differentiates itself from the sibling list-and-match tools by contrasting free-text input with their exact matching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it ('Meant for phones named in free text') and why the alternative fails ('the other tools match brands and models exactly, so a guessed spelling returns an empty list'). An agent knows both the trigger condition and the consequence of choosing the wrong sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. Defaults to 100, which filters out barely-sampled devices whose averages are meaningless. Lower it only when a query returns too few rows. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/openWorld, so the bar is lower, and the description adds real behavioral context: results are capped at `limit` rows and ranking is computed over each device's own lifetime aggregate (not live data). It doesn't mention response shape, but an output schema exists so that omission is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs with the core purpose and the superlative-answer benefit front-loaded. Slight redundancy between the prose alternatives ('last longest') and the later pairing example ('best battery life'), but every sentence carries useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a filtered leaderboard with an output schema and full annotation coverage, the description supplies the needed semantic model: individual-device scope, lifetime aggregation, row cap, and metric/order pairing. Nothing critical to invoking it correctly is missing, though sibling disambiguation remains implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, and the description earns above that by explaining the metric/order relationship with concrete pairings (hottest = temperature_c + desc, fastest AC charging = ac_charge_hours + asc, best battery life = discharge_hours + desc). This cross-parameter guidance is not derivable from the schema fields individually, making it substantive added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (rank) and resource (INDIVIDUAL devices by battery metric) and explicitly distinguishes itself as 'the general-purpose leaderboard'. The emphasis on INDIVIDUAL devices separates it from model-level siblings like top_models, and from the uptime-specific siblings top_devices_by_uptime / top_devices_by_live_uptime.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear triggers ('which phones run hottest / last longest / charge fastest') and explains the superlative-question use case ('single small call instead of enumerating the fleet'). It also notes the optional brand/model narrowing. However, it never explicitly names when to prefer a sibling (e.g. uptime-specific tools) over this one, so the when-not guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and a closed-world scope, so safety is covered. The description adds genuinely useful semantics beyond that: the precise meaning of the 'live' filter (uptime still climbing, not yet rebooted past recorded max) and the presence of a per-entry `url`. It does not cover rate limits or ordering guarantees, hence not 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the differentiator ('Same as X, but restricted to...') so the distinguishing condition arrives in the first clause. The trailing URL/output sentence is mildly redundant given an output schema exists, keeping it just under a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values, and the annotations carry the safety profile. What remains — what 'live' means and why this differs from the historical ranking — is fully covered, so an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so brand, limit, and model are already fully documented, including defaults and the any-brand behavior. The description adds no filter syntax or format detail beyond the schema, so baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource (top devices by live uptime) and explicitly frames it relative to the sibling `top_devices_by_uptime`, defining 'live' as devices that have not rebooted past their recorded maximum. An agent can distinguish this ranking from the historical one without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names the alternative tool (`top_devices_by_uptime`) and gives the selection condition: 'live' champions right now versus historical record-holders. It stops short of a directive when-not-to-use statement, but the contrast is clear enough to route an agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description still adds real value by defining the ranking metric (max uptime between reboots) and disclosing two response fields (device_uid, url) with a deep-link target, which clarifies what the tool actually produces.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the metric definition, then filters, then downstream usage — a sensible order. The 'champions of staying powered on for weeks/months' clause is colorful but mildly redundant with the preceding sentence, costing a little tightness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be enumerated, and the description still usefully names device_uid and the url for chaining. The remaining gap is disambiguation from top_devices_by_live_uptime and top_devices, which the description leaves to the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with brand/model/limit all documented in the schema including case-sensitivity and default behavior. The description only restates 'optionally filter by brand and/or model', adding the combined 'and/or' framing but no new syntax or format detail. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource and pins down the exact metric: devices ranked by 'longest single uptime ever recorded between reboots (max_elapsed_time)'. This definitionally separates it from the near-named sibling top_devices_by_live_uptime, even though that sibling is not named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a use case ('find which physical phones in the fleet are champions of staying powered on') and a downstream hand-off to device_summary, which is genuine routing help. But it never states when to prefer this over top_devices, top_devices_by_live_uptime, or device_ranking, which is the highest-risk confusion given the near-identical sibling name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. | |
| 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_devices | No | 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/closed-world, so the safety profile is covered. The description goes beyond them by disclosing the ranking statistic (MEDIAN, with mean returned alongside) and the outlier-resistance rationale, which materially affects how results should be interpreted. It stops short of describing pagination or empty-result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then usage examples, then ordering semantics and filter guidance. Every sentence adds information; no filler or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists so return-shape explanation is not required, and the description fully covers aggregation level, ranking statistic, direction logic, and filter behavior. An agent has everything needed to invoke this correctly against its siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3, but the description adds real value beyond it: it ties the order direction to metric polarity ('fastest charging is ac_charge_hours + asc'), and explains the purpose of brand and min_devices rather than just restating them. The median-vs-mean semantics also inform how metric values are ranked.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Rank device MODELS by any battery metric') and adds the aggregation scope ('aggregating across every device of that model'), which cleanly separates it from sibling model_summary and device_ranking. The restated example questions make the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative it replaces ('questions that would otherwise need one model_summary call per model'), gives three concrete question archetypes, and explains when to use the brand and min_devices filters. Nothing 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
brandsdevice_rankingdevice_summarydevicesfleet_summaryfleet_totalsmodel_summarymodelssearchtop_devicestop_devices_by_live_uptimetop_devices_by_uptimetop_modelsReal UK MOT failure data by car model and mileage, aggregated from official DfT test results.
Live model catalog with prices and measured uptime, rankings, credits and spend, spend-capped chat.
Live data on AI agents, APIs and models: prices, free tiers, limits, outages, real-world usage.
App downloads and chart ranking trends for iOS and Android. Free key at trendsapi.ai
Add one secure layer between your agents and this server.