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

With no annotations, the description carries the full behavioral burden and does well: it specifies the exact return shape, the protocol used, and the symlink resolution behavior. These details meaningfully prepare the agent for what to expect. It could also mention error behavior for missing paths, but this is a minor gap for a read-only listing tool.

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 compact and every sentence earns its place: purpose, protocol advantage, return shape, common roots, and symlink behavior. Important details are front-loaded, and there is no filler or repetition of schema text.

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?

Since no output schema exists, the description compensates by fully documenting the return value structure. It also provides practical path guidance and a notable behavioral edge case. It is sufficiently complete for an agent to invoke the tool correctly, though very minor details like non-existent-path behavior are absent.

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?

Both parameters are already fully described in the schema (100% coverage), so the baseline is 3. The description adds value by giving concrete example values for remotePath and clarifying that paths are absolute, which goes beyond the schema's generic example.

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 lists files and directories at a path, with a specific verb and resource. It also provides common root examples that make the scope concrete. However, it does not explicitly differentiate itself from sibling tools like device_file_find or device_file_stat.

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 implies usage for browsing device storage and includes common roots like /sdcard/Download, which helps an agent pick appropriate paths. It also notes the file-sync protocol avoids a shell roundtrip, hinting at an advantage over shell-based alternatives. But it never states explicit when-to-use or when-not-to-use guidance versus sibling file tools.

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