ACTION_GET_BATTERY

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

With no annotations, the description carries the full burden and does a fair job: it discloses the output variable contract, the 0–100 range of battery_level, the edge case that battery_charging stays true when full, the presence of success/error variables, and that results arrive as a variable-snapshot JSON with ${var} interpolation in string params. It never states that the operation is read-only/no-permission, but the wording 读取 makes the read semantics unambiguous.

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 action, then the output contract, then the interpolation/return-format note — logical order with no padding. Minor defect: a doubled period ("。。") and the output-variable list slightly duplicates the schema's output_var note.

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?

No output schema exists, so the description must define the return surface itself — and it names every returned variable, their ranges and edge cases, plus the snapshot/interpolation behavior. Combined with 100% schema coverage of the four generic control params, an agent has everything needed to call and consume this 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 description coverage is 100%, so the four parameters (require, on_error, output_var, node_timeout_ms) are already fully documented in the schema and the description adds nothing about them. It does add meaning about the return values and interpolation, but that is output-side, not parameter-side; 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 opens with a specific verb+resource (读取电量和充电状态) and enumerates the exact output variables (battery_level, battery_charging, battery_success, battery_error), so the agent knows precisely what this tool produces. It does not explicitly differentiate itself from nearby siblings such as ACTION_GET_DEVICE_INFO or ACTION_GET_STORAGE_INFO, so it falls short of a 5.

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 only implied by the resource name — an agent can infer 'call this when you need battery state' but there is no explicit when-to-use/when-not guidance and no named alternative for richer device queries. No prerequisites or preconditions are stated.

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