Consumo de batería por programa

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

Annotations only provide readOnlyHint=true, so the description carries the burden of explaining behavior. It discloses that energy_impact is a relative POWER score from top (not watts), that it excludes GPU and therefore the ranking uses energy_impact plus gpu_percent, and that measurement lasts about 2 seconds. These non-obvious traits help an agent interpret results and avoid misrepresenting the output.

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 four compact Spanish sentences, each delivering necessary information: purpose, technical interpretation, output contents, measurement duration, and use case. It is slightly dense with technical caveats, but there is no redundancy or fluff; 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?

Though there is no output schema, the description tells the agent exactly what results will contain: per-program CPU and GPU percentages, total GPU usage, and the top GPU-using programs, along with the ordering rationale. It also explains the relative unit and measurement duration, covering everything an agent needs to invoke and interpret the tool for this one-parameter read-only operation.

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 input schema fully documents the only parameter 'limit' with default, minimum, maximum, and a Spanish description, giving 100% schema coverage. The tool description adds no parameter-specific detail beyond what the schema already provides. A baseline score of 3 is correct because 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?

The description opens by answering 'Qué programas consumen más batería ahora mismo', which clearly states the tool's purpose and resource. It further differentiates from siblings by specifying that it reports per-program battery impact and includes GPU usage caveats. Even though it is phrased as a question, an agent can immediately identify what the tool does and how it differs from get_battery, get_cpu, or get_top_processes.

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 gives an explicit trigger phrase: 'Úsalo para ¿qué se come la batería?', telling an agent exactly when to select the tool. However, it does not name alternative tools or explain when not to use it in favor of siblings like get_battery or get_top_processes. This is clear contextual guidance but lacks formal exclusion criteria.

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