apk_preview_start_session

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

The annotations already indicate a state-changing operation, and the description adds that it starts a dedicated AVD and saves a shared session. This is useful context, but it does not disclose boot/wait behavior, what happens if an AVD is already running, session cleanup, or failure/timeout behavior. The timeout_seconds parameter hints at wait behavior, but the description does not confirm it.

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 a single concise sentence with no wasted words, and the main action is front-loaded. It is appropriately short, though it could have included a bit more operational detail without becoming bloated.

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?

While an output schema exists, so return value documentation is less critical, the description is still incomplete for a state-changing session lifecycle tool. It lacks usage ordering, parameter meaning, and behavioral details about the shared session. An agent would likely need to inspect the schema and sibling tools to understand how and when to call it correctly.

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 0%, so the description carries the burden of explaining the parameters, but it does not mention avd, visible, or timeout_seconds at all. Even though the parameter names are somewhat self-explanatory, the description adds no meaning about valid avd values, the effect of visible, or how timeout_seconds is used.

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 uses a specific verb and resource: 'Start a dedicated AVD and save shared session.' This conveys the core purpose and distinguishes it from siblings like list_avds, install_apk, or launch_app. However, it does not explicitly differentiate it from the related session lifecycle tools beyond naming the session concept.

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 no guidance on when to use this tool versus alternatives such as apk_preview_launch_app or apk_preview_stop_session. It does not state that this should be called before installing/launching, nor does it mention any prerequisites or ordering. Usage context is only weakly implied by the term 'session'.

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