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

Annotations already indicate idempotentHint=true and readOnlyHint=false, and the description aligns without contradiction. It adds valuable behavioral context: handles 'already booted' as success, tracks performance metrics, waits intelligently, and notes that opening the GUI increases boot time. It also warns that first boots may be slower. These go beyond the annotations and help the agent anticipate side effects and edge cases.

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 long but well-structured with clear headings: advantages, parameters, returns, examples, related tools, device support, notes. Each section serves a purpose, and the most critical information (purpose and advantage) is front-loaded. Some promotional content (e.g., emoji-laden advantage list) is arguably redundant for an agent, but it does convey the tool's unique value proposition. Overall, it earns its length without being 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?

The description covers every aspect needed to invoke the tool correctly: parameters with defaults, return structure, multiple examples (specific device and quick boot), related tools for discovery and shutdown, device support (simulators only), and edge-case notes (already booted, first boot slower). With no output schema, the 'Returns' section compensates adequately. This is a thorough, self-contained description for an agent.

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 schema provides zero descriptions, but the description fully explains all three parameters: deviceId (accepts UDID or 'booted'), waitForBoot (default true, waits for complete boot), and openGui (default true, opens GUI). It also clarifies return data (boot status, device info, boot time, metrics). This is a comprehensive compensation for the schema's lack of descriptions, giving the agent everything needed to construct correct calls.

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 function: it boots a simulator with added intelligence. It opens with 'Prefer this over 'xcrun simctl boot'' and lists specific advantages like performance tracking and learning. The name and title already indicate booting, and the description adds distinct value by highlighting enhanced features, making it unambiguous among the many simctl-* siblings.

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 explicitly says 'Prefer this over xcrun simctl boot' and lists advantages, establishing when to use this tool over the raw CLI. It also references related tools like simctl-list for discovering devices, simctl-suggest for recommendations, and simctl-shutdown for stopping, providing context for when this tool is appropriate. However, it doesn't explicitly state when NOT to use it (e.g., if you need to launch an app, use simctl-launch), but the related-tools section gives a strong implicit routing.

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