list-devices

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

With no annotations provided, the description fully discloses behavioral traits: return structure ({devices, avds}), platform discriminators, state and kind fields, headless behavior for additional device sets, discovery mechanisms (CDP ports, adb devices), and silent omission when CLIs are unavailable. No annotation contradiction exists.

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 lengthy but every sentence earns its place, covering essential details for each device type. It is front-loaded with a clear one-line summary, followed by structured elaboration. No fluff or redundant statements.

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?

Despite having no output schema and no annotations, the description provides complete context: return format, field meanings, state semantics, platform-specific interactions, and failure modes. An agent can confidently invoke the tool and interpret its results.

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 tool has zero parameters and the schema is empty, so there is nothing to add for parameter semantics. Baseline 4 applies, and the description appropriately focuses on output semantics instead.

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 ('List') and clearly enumerates the scope: iOS simulators, Android emulators, physical Android devices, running Chromium apps, and Vega devices. This fully distinguishes the tool from all siblings, none of which are list tools.

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?

Explicitly instructs to use the tool 'at the start of a session' and provides actionable guidance for different target types: use boot-device for stopped Vega VVDs and Chromium apps, use describe/tv-remote/keyboard for TV targets instead of gesture tools, and explains how physical devices are connected.

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