ACTION_GLOBAL_KEY

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the privilege prerequisite (Shizuku/root or accessibility), a shell-keyevent-then-accessibility fallback chain for the four navigation keys, and which keys are accessibility-only or shell-only. It does not cover failure reporting beyond naming the key_success output variable.

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?

Very compact and front-loaded: purpose first, then prerequisite, then output contract, then interpolation note. The nested parenthetical ("（需...（见 key 说明））") is slightly dense but every clause carries 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?

There is no output schema, but the description names the return contract (key_success) and the variable-snapshot JSON shape, and it covers prerequisites and per-key channel constraints. The main remaining gap for an agent is disambiguation from ACTION_GLOBAL_NAV.

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 per-key channel semantics in the enum description already do the heavy lifting and the baseline is 3. The description adds only marginal meaning beyond the schema in this dimension, namely the ${var} interpolation support and that string params are interpolated.

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 ("全局按键" – press global hardware/navigation keys) and enumerates the supported keys (back/home/recents/notifications/enter). However, it never distinguishes itself from the sibling ACTION_GLOBAL_NAV, which by name sounds like it covers the same navigation-key territory, so an agent cannot route between the two from the description alone.

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?

Conveys the precondition ("需 Shizuku/root 或无障碍") and, via the key description, which keys work through which channel with fallback ordering. It gives no explicit when-to-use vs when-not guidance and names no alternative tool, so routing between this and ACTION_GLOBAL_NAV remains inference.

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