Android list Apps

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: listing fails by throwing rather than returning empty, so count:0 is meaningful; user-installed only by default; concurrency-safe. These go beyond annotations and help the agent understand edge cases.

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 information-dense but every sentence carries purpose. It front-loads the core action and purpose, then dives into filtering and failure behavior. Slightly long, but no fluff; the structure (purpose → query warning → system packages → failure semantics → concurrency) is logical and easy to parse.

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 tool with three parameters, no output schema, and moderate complexity, the description covers everything an agent needs: what it lists, what fields are enriched, filtering semantics, the failure mode, and concurrency. The rationale for not matching labels is especially helpful for agents interacting with non-English UIs. No missing critical information.

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 all parameters with descriptions (100%). The description adds extra nuance: query is case-insensitive substring against package name and explicitly warns that display labels will never match (since Android exposes no label over adb). It also clarifies the semantics of include_system and the default of device selection, which the schema already states but the description reinforces with real-world context.

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 resource: 'List the packages INSTALLED on a device', and immediately clarifies it's an enriched pm list. It distinguishes itself from siblings by explicitly noting it should run before opening an app because package names cannot be guessed, which differentiates it from android_launch_app and android_app_info.

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 explicit when-to-use guidance: 'Run this BEFORE opening an app' and explains why (package name cannot be guessed). It also provides an alternative for opening by label (android_find_text + android_tap_text) when labels don't match. The include_system parameter is explained with the context of what 'open <app>' means, making usage clear.

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