query_excessive_wakeup_rate

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

With no annotations, the description carries the behavioral disclosure. It explains the metric definition, the daily aggregation limitation, and how to request rolling averages via specific metrics. This goes beyond the schema, though it repeats the DAILY enum and doesn't mention pagination or output format. The added context on metric interpretation compensates for missing 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?

The description is a tight two-sentence paragraph, front-loaded with the primary purpose, then adding metric context and aggregation guidance. No filler or redundant detail, every sentence earns its place.

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?

Despite having 8 parameters and no output schema, the description adequately covers the metric's meaning, the rolling-average option, and the daily constraint. It does not explain the return format, but for a query tool with a clear metric definition, this is sufficient. The schema covers parameter details, so the description's role is to provide metric-specific context, which it does.

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 covers 100% of parameters, so baseline is 3. The description adds value by explaining the default metrics (excessiveWakeupRate and distinctUsers), how to override them with rolling average metrics, and confirms the daily-only aggregation. This enriches the 'metrics' and 'aggregation_period' parameters beyond their schema descriptions.

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 clearly states the tool queries the excessive wakeup rate metric, defines it, and distinguishes it from sibling metrics by specifying it's a battery-drain metric. The verb 'Query' and resource 'excessive wakeup rate' are explicit, and the context about background work separates it from other Vitals queries.

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 provides usage context by explaining the metric is battery-drain related and counts background users, but does not explicitly state when to choose this tool over alternatives like query_stuck_wakelock_rate or when-not to use it. No exclusion criteria or alternative tool names are given.

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