BatterySnap

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 adds useful behavioral context the annotations do not: the unbounded list can be very large, and `fields` names that are unknown are silently ignored.

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?

Return shape is front-loaded, followed by filtering, field projection, and paging advice; each sentence has a job. It is somewhat wordy in restating parameter behavior the schema already carries, which keeps it below 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 detail return values, and the annotations carry the safety profile; the remaining gaps an agent would care about (list size, paging, single-brand routing) are all covered.

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 including defaults and bounds. The description restates the filter pairs, `fields`, and `limit`/`offset` paging but adds no syntax or semantics beyond what the schema provides, 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 device brands with battery statistics) and enumerates the returned aggregates (model count, device count, max_devices_per_model, url). It also carves out its scope against the `search` sibling, so an agent can tell what this tool is for without opening the 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?

Gives concrete operating guidance: prefer `search` when resolving a single brand by name, and pass `limit` unless the full list is genuinely needed. It stops short of a full when-not statement (e.g. when to prefer model- or device-level siblings), but the alternative-tool routing is explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: what each of the two cohorts means and which one answers the degradation question, which the annotations cannot convey. It stops short of stating cost, rate limits, or minimum sample-size caveats for sparse cohorts.

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 user question it answers, then the return contents, then the routing advice — no wasted sentences. Every clause either defines scope, describes output, or steers tool selection.

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 and an output schema, the description covers the remaining gaps: cohort semantics, the routing alternative, and what the call returns. Nothing an agent needs in order 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 coverage is 100% — the schema already documents both parameters in depth, including every metric enum value and its unit/direction. The description adds only that ranking is against same-model and fleet cohorts, not new per-parameter meaning, 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 (rank) and resource (one device's battery metric) and pins the scope precisely: ranked against same-model peers AND the whole fleet in one call. It explicitly differentiates itself from siblings device_summary and model_summary, so an agent can select it 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?

Gives an explicit when-to-use rule ('Prefer this over fetching device_summary + model_summary and comparing by hand') and names the concrete alternative plus the reason (single call, percentile computed directly). It also advises on cohort selection — the model cohort answers 'is this device degraded', the fleet cohort contextualizes the model itself.

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

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

Annotations already cover read-only, idempotent and closed-world, and the description adds genuinely new behavioral context: metrics are aggregated only from that device's own snapshot history, duplicate brand/model devices appear as separate entries, matching is case-insensitive against either street name or raw Android model, and each entry carries a public `url`. It does not say what happens on a no-match (empty list? error) or whether result ordering/pagination exists, which keeps it below 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?

Purpose and the per-device-vs-aggregate clarification are front-loaded and well structured. However, the long enumeration of per-device fields ('brand, resolved model ..., snapshot count, activity window ..., average / min / max battery temperature ..., awake-ratio, discharge speed ...') largely reproduces the output schema and bloats the definition, as does the repeated matching-rule sentence.

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 read-only two-parameter lookup with a full output schema and complete schema descriptions, the description covers the semantics that matter: what one entry represents, non-aggregation across devices, dual-name model matching, and response trimming. Gaps are minor (empty-result behavior, ordering/pagination limits) and the return-value explanation is provided by the output schema rather than the description.

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` members and `fields` are already documented in the schema. The description restates the same matching rule ('case-insensitively against either the resolved street name ... or the raw Android model identifier') and the same `fields` intent ('keep only specific attributes'), adding no new syntax, limits, or format detail beyond the structured data. 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 list of individual physical devices matching ... (brand, model) pairs') and immediately scopes the granularity: 'Each entry ... describes ONE specific device ... not aggregated across devices.' That contrast distinguishes it from aggregate siblings like model_summary, device_ranking and fleet_totals without the agent needing to open another 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?

Usage is implied rather than stated — the reader infers this is the right tool when they need per-device rows for known brand/model pairs, and 'Pass `fields` to keep only specific attributes per device and avoid bloated responses' gives a concrete efficiency rule. But no sibling is named (e.g. 'use search for free-text lookup, device_summary for one device') and no exclusion is given, so routing relies on inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds real value beyond them: values are pre-computed from full snapshot history, no raw timeseries is returned, and the two aggregation windows (~2 weeks, ~2 months) are disclosed. It also explains the `url` field's meaning, though it doesn't discuss latency or data freshness beyond the window sizes.

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?

One dense paragraph that front-loads the core purpose and metric list, with the URL and pre-computation caveats following. Every sentence carries information, though the metric enumeration is long enough that a bulleted structure would read faster.

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 single-parameter read tool with an output schema, the description covers purpose, scope, aggregation windows, return nature (pre-computed, no raw timeseries), and the extra `url` field. 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 coverage is 100% and the single parameter is already documented as a stable device UUID from the `devices` tool, so the description adds little parameter-level meaning. Baseline 3 applies when the schema does the heavy lifting.

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 metrics returned (avg/min/max temperature, battery level, charge/discharge times, awake ratio). The 'ONE specific device' scoping plus the metric list clearly separates it from fleet_summary, model_summary, and region_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 description makes the selection condition explicit ('ONE specific device') and points to the `devices` tool as the source of the required device_uid, which is a useful routing hint. It stops short of stating when-not to use it or naming a specific alternative for multi-device queries, so it falls just below the top band.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), but the description adds real behavioral context beyond them: the minimum-5-device refusal rule and the fact that region is derived from device time-zone settings rather than GPS/IP. It stops short of covering cost/latency or what happens with an unrecognized brand or country value.

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?

Four tight sentences with no filler: scope first, return values second, intended comparison use third, refusal and alternative last. Each sentence carries a distinct decision-relevant fact.

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 needn't spell out the payload; it instead spends its budget on scope, the refusal precondition, and sibling routing. Nothing an agent needs to call this 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 per-parameter meaning of brand, country and continent is fully documented in the schema, including the time-zone derivation and the country/continent intersection. The description mostly restates that filtering hierarchy; its only addition beyond the schema is that the 5-device refusal applies to region scope.

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?

Specific verb+resource ('aggregate battery metrics across the entire fleet') with explicit scope modifiers (brand, country/continent) and the returned statistics set. It names model_summary as the metric-parallel sibling, so an agent can tell it apart from the other summary tools without opening the 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?

States the intended use ('fleet-wide baselines that a single device or model can be compared against') and gives an explicit exclusion with an alternative: 'to compare several regions at once use region_summary'. It also states a precondition that blocks invocation (region scope under 5 devices is refused).

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

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 adds genuine behavioral context beyond that: the values are live/running rather than cached, they are raw database counts, and one of them is the timing of the last insert batch — useful for judging freshness. It stops short of describing staleness windows or refresh cadence.

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 tightly packed sentences. The enumerated counters are front-loaded, the usage condition follows, and the sibling differentiation closes it out — no sentence 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-shape explanation is not required, yet the description still names each counter so the agent knows what to expect. For a zero-parameter read-only tool with full annotation coverage, nothing an agent needs to invoke 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly adds no parameter noise.

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?

Names a specific resource (fleet-wide counters) and enumerates exactly what is counted: devices, models, snapshots, sessions, ingest rate, and last batch timing. It explicitly contrasts itself with the sibling `fleet_summary`, so an agent can separate the two 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?

States the triggering question type ('how big is the dataset / how fast is it growing') and names the alternative (`fleet_summary`) plus the condition that distinguishes them (per-device aggregation vs. raw counts). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds genuinely non-obvious behavior: grouping by resolved street name with several raw Build.MODEL ids collapsed, lexicographically-smallest representative raw_model_code, url nullability rules, and that unknown field names are silently ignored.

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 and mostly useful, but it restates return attributes that the output schema already carries, and one clause is malformed ('null when either is null; `raw_model_code` is null'), which adds noise rather than clarity.

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 7-parameter read tool with a full output schema, the description supplies the caveats an agent needs (grouping, nullability, filtering/paging) without over-explaining. Return-value detail is partly redundant with the output schema, keeping it just below a 5.

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 prescribing the composed pattern (sort='device_count' + small limit + fields instead of fetching and sorting the whole list) and explaining the min/max_device_count filtering intent beyond the literal schema wording.

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 precise verb+resource ('Return the mobile devices models of the given brands') and enumerates the attributes returned, so the agent knows exactly what it gets. It never explicitly contrasts with the nearby siblings (model_summary, top_models), so the differentiation is implicit rather than stated.

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 usage patterns: pass min/max_device_count to filter, combine sort='device_count' with a small limit for 'most devices' questions, use fields to shrink entries, omit brands to span all brands. It stops short of saying when to prefer a different sibling tool instead of this one.

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

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

Beyond the readOnly/idempotent annotations, it discloses the minimum-sample failure mode, how region filtering is derived (time-zone setting, not GPS/IP), the exact aggregate statistics returned, and the null semantics for raw_model_code and url. That is precisely the context annotations cannot carry.

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 and stats list, then tapers into derived-field and filtering notes with a compact bullet structure. Minor waste: the escaped '%%' artifact, and a bullet explaining return fields that the output schema already covers.

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 still usefully explains the non-obvious derived fields and their null conditions, plus the sample-size gate that governs whether the call succeeds. An agent has everything needed to decide and invoke 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 coverage is 100%, so country/continent are already documented, but the description adds the failure threshold tied to filtering ('fewer than 5 devices ... remain') and how the two filters combine as an intersection. It stops short of adding anything on brand/model matching beyond what the schema says.

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 with explicit scope: 'Aggregate battery metrics across ALL devices of a given brand+model.' The ALL-devices scoping and the comparison framing ('compare a single device against its model average') make it clearly distinct from device_summary without the agent needing to open 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?

Gives concrete use cases ('characterize how a model behaves in the field', 'compare a single device against its model average') and a hard precondition ('the call fails when fewer than 5 devices of the model remain'). It never names a sibling tool as the alternative, so routing is implied rather than explicit.

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

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

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

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

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

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

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

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

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

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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

Annotations already declare readOnly/idempotent/closed-world, and the description goes well beyond them by disclosing the matching algorithm (substring-based, case-insensitive over brand, resolved model name, and raw Build.MODEL) and the ranking rule (exact match, then popularity). That is the kind of behavior an agent needs to predict result quality and ordering.

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 tight paragraphs with the purpose front-loaded and the matching/ranking detail second. Every sentence carries information, though the 'meant for phones named in free text' clause slightly overlaps the preceding sentence.

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 explanation, and annotations cover the safety profile. The description supplies the remaining decision-relevant context: why exact-match siblings fail and how results are matched and ranked.

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 parameters are already documented, including the examples for 'query' and the separate per-list capping of 'limit'. The description adds no syntax or format detail 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?

The description states a specific verb and outcome ('resolve free-form user text into the canonical brand / model identifiers') and immediately separates this tool from the sibling 'brands'/'models' tools, which match exactly. An agent can tell what this does and why it exists without opening the 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 clearly says when to use it ('meant for phones named in free text') and explains the failure mode that motivates it ('the other tools match brands and models exactly, so a guessed spelling returns an empty list'). It does not name a specific sibling alternative or state explicit when-not conditions, which keeps it short of a 5.

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

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

Annotations already declare readOnly/idempotent/closed-world, so safety is covered; the description adds genuinely non-obvious behavior: ranking is over each device's lifetime aggregate rather than a live window, output is capped at 'limit' rows, and brand/model filters are optional narrowing rather than required scope. It does not discuss how ties or devices with sparse data outside min_snapshots are surfaced, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight paragraphs ordered by importance: what it does, how to pair metric with order, and what it does not do. No filler sentences and no repetition of schema content beyond the illustrative metric/order examples that aid recall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

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

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

With 100% schema coverage the per-parameter definitions are already handled, so the description's contribution is cross-parameter: it pairs metric direction with order ('hottest = temperature_c + desc', 'fastest AC charging = ac_charge_hours + asc'), which the schema only states generically. It also signals that brand/model are optional narrowing. The min_snapshots tuning advice is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Rank INDIVIDUAL devices by any battery metric') and immediately frames it as 'the general-purpose leaderboard', which separates it from model-level (top_models) and uptime-specific (top_devices_by_uptime, top_devices_by_live_uptime) siblings. The capitalized INDIVIDUAL makes the unit of ranking unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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 description's job is to add semantics — and it does, defining the filter predicate ('uptime is currently still climbing') and disclosing that each entry carries a `url`. It says nothing about result size limits, ordering guarantees, 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?

The distinguishing clause is front-loaded and compact. The follow-up sentence ('These are the devices that are live champions...') largely restates the preceding clause, adding a little redundancy, and the `url` detail is mild overlap with the output schema.

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 annotations covering safety, an output schema covering return values, and full schema coverage on parameters, the description supplies the one thing structured data cannot: the meaning of the 'live' filter. It is sufficient to call the tool 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 the three parameters (brand, model, limit) are already fully documented in the schema. The description adds no further syntax, casing, or interaction details beyond what structured data provides; 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?

The description names the sibling it mirrors and the precise restriction that separates it: devices that have not yet rebooted past their recorded maximum. An agent can distinguish this from `top_devices_by_uptime` and `top_devices` 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?

It clearly frames the use case ('live champions right now' vs 'historical record-holders'), which effectively routes the agent between this tool and `top_devices_by_uptime`. It stops short of an explicit when-to-use / when-not-to-use statement, but the contrast is unambiguous.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, so the safety profile is covered. The description adds genuinely useful output context: each entry carries a device_uid usable with device_summary and a url to an interactive history page, which goes beyond 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?

Three sentences, front-loaded with the metric definition, then filters, then output affordances. Each sentence carries information, though the 'champions of staying powered on' flourish is slightly decorative.

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-value explanation isn't required, yet the description helpfully points at device_uid and the url. With full parameter coverage and clear metric scoping, 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, model, and limit are already fully documented with defaults and ranges. The description only restates that brand/model are optional filters, adding no syntax or matching nuance beyond the schema (e.g., the case-insensitive behavior is only in the schema).

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 with the exact metric ('longest single uptime ever recorded between reboots (max_elapsed_time)'). This precisely distinguishes it from the close sibling top_devices_by_live_uptime, which ranks on live uptime rather than a historical max.

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?

Provides a use case ('find which physical phones are champions of staying powered on') and notes that brand/model filters are optional. However, it never names an alternative or states when NOT to use this tool, which matters given the sibling top_devices_by_live_uptime and device_ranking.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so safety is covered. The description adds genuinely useful behavior: ordering is by per-model MEDIAN (outlier-resistant) with the mean returned alongside, and min_devices defaults to 3 to prevent a single outlier phone from winning. It stops short of 5 only because output shape and any performance/pagination characteristics are left to the output schema.

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 verb/resource, then the decision rule, then the ordering semantics and parameter guidance. Every sentence carries information an agent needs; there is no filler or restatement 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?

For a 7-parameter ranking tool with a full output schema, the description covers purpose, alternatives, aggregation method, outlier handling, and region-filter interactions. Nothing an agent needs in order to choose and call this tool correctly is missing, and return values are correctly delegated to the output schema.

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 clears that bar by framing what the filters mean in practice (brand = rank within one manufacturer; country/continent = models as they behave in one region, e.g. heat in hot climates) and by explaining the min_devices rationale. It does repeat some schema content (order direction examples, region-raised floor), which keeps it from a 5.

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 (device MODELS), plus the aggregation semantics (per-model median across all devices of that model). It explicitly distinguishes itself from model_summary by naming the per-model-call alternative it replaces, and from device_ranking/top_devices by operating on models rather than 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 question patterns ('which phone model has the best battery life', 'which charge fastest', 'which run hottest') and the explicit alternative ('would otherwise need one model_summary call per model'). It also tells the agent when to use brand, min_devices, and country/continent, including the tricky heat-in-hot-climates case.

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