appium_session_management

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

Annotations already provide readOnlyHint=false and destructiveHint=true, so the agent knows this tool can mutate state. The description adds a small behavioral distinction between detach ('forget') and delete ('stop'), which is useful. However, it does not disclose important traits such as attach not taking ownership of the remote session lifecycle or detach leaving the real remote session intact—details that would prevent misuse and are only found in the parameter schema.

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, front-loaded sentence that states the general purpose and enumerates all actions without filler. It is compact and easily scannable. It is slightly run-on, but every clause earns its place, so the efficiency is strong.

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 multi-action tool with five parameters, the full definition is quite complete: the action parameter description covers local vs remote modes, prerequisites (select_device, prepare_ios_simulator), explicit prohibitions ('NEVER invent a localhost URL'), and examples. The tool description alone is thin, but the schema richness compensates. The absence of an output schema is partially mitigated by the list action describing its returned fields, though create/select return shapes are not described.

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 100%, so the baseline is 3. The complete parameter descriptions in the schema (modes, examples, JSON serialization, required capabilities for attach) already carry the full semantic load. The tool description itself does not add parameter meaning, but given the high coverage, no further description contribution is required.

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 names the resource (Appium sessions) and lists six concrete actions (create, attach, detach, delete, list, select), so the tool's scope is clear and visibly distinct from device-control, element, and file siblings. The verb 'Manage' is generic, but the action enumeration compensates and gives the agent a precise idea of what the tool does. It does not explicitly name an alternative sibling, so a 5 is not warranted.

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 siblings like select_device, prepare_ios_simulator, or the appium_* device-control tools. It only implies that session management is its job. Although the action=create parameter description later provides rich workflow rules (e.g., 'Use select_device tool FIRST', 'SKIP select_device tool entirely'), that guidance is not in the tool description itself, and the description carries no exclusions or alternatives.

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