select_device

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

Annotations are minimal (readOnlyHint false, openWorldHint false), so the description carries the behavioral burden. It discloses key traits: the tool auto-selects when only one device is found, requires a second call with deviceUdid when multiple are found, and must not be used for remote servers. It does not explicitly describe the return format or what happens if no devices are found, but the workflow is otherwise transparent.

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 longer than average, but highly structured with clear workflow numbering and front-loaded local/remote distinction. Minor redundancy exists in repeated references to appium_session_management (action=create) and prepare_ios_simulator, but these repetitions reinforce the handoff rather than adding noise.

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 no output schema, the description covers nearly everything an agent needs: local vs remote handling, user-asking requirements, auto-selection behavior, re-call semantics, and follow-up steps. It is slightly incomplete in not describing the tool's response shape or fallback behavior when zero devices are found, but those are secondary given the explicit workflow.

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 coverage is 100%, so the schema already documents each parameter. The description adds meaningful usage sequencing: call first with just platform (and iosDeviceType for iOS), then call again with deviceUdid if multiple devices are found. It also reinforces that iosDeviceType is required for iOS, going slightly beyond the static schema.

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's specific purpose: 'Discover and select a device for LOCAL Appium servers ONLY.' It explicitly distinguishes the tool from remote-server workflows and names sibling tools like appium_session_management and prepare_ios_simulator, so an agent can reliably tell when to use it.

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?

Usage is exceptionally well specified. It says 'DO NOT use this tool for REMOTE Appium servers' and gives the exact alternative ('handled via capabilities on appium_session_management'). The numbered local workflow tells the agent when to call, when to ask the user, when to re-call with deviceUdid, and what to do next.

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