appium_prepare_ios_real_device

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

Annotations are minimal (readOnlyHint=false, openWorldHint=false), leaving the description to carry the burden — and it delivers. It discloses cache semantics (WDA download and unsigned IPA cached per version, signed IPA rebuilt every call), mode-dependent side effects (list-only vs download/package/resign), wildcard profile handling with bundle ID substitution at sign time, and the external toolchain requirements. Nothing here contradicts readOnlyHint=false.

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?

Longer than a typical tool description, but the tool genuinely warrants it — a two-mode flow, caching behavior, signing mechanics, and a cross-tool handoff all need explaining. The purpose is front-loaded, the modes are numbered for easy parsing, and every sentence (prerequisites, cache rules, capabilitiesHint routing) carries information without repeating the schema.

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?

With no output schema and sparse annotations, the description compensates well: it states what mode 1 returns (profile list with recommendedForWda flags), what mode 2 returns (capabilitiesHint), the prerequisites, and the downstream call. The residual gaps are the full response envelope shape and failure cases (e.g., no profiles found, device not paired), which an output schema would normally cover.

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%, which sets a baseline of 3, but the description adds meaning above the schema: it explains the two-mode flow keyed to provisioningProfileUuid presence, the wildcard ('*') profile substitution detail, and how forceRebuild interacts with the per-version cache of the WDA download and unsigned IPA. It also clarifies the capabilitiesHint output contract that connects to session creation.

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?

Opens with a specific verb+resource statement — 'Prepare an iOS real device for Appium testing in a single call' — then details a concrete two-mode mechanism, so there is no ambiguity about what the tool accomplishes. It is clearly distinguished from siblings: appium_session_management is positioned as the downstream consumer of capabilitiesHint, select_device is referenced for UDID discovery, and the real-device provisioning focus sets it apart from prepare_ios_simulator.

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 an explicit usage sequence: first call without provisioningProfileUuid to obtain the profile list, present it to the user, then call again with the chosen UUID. It also states hard prerequisites (macOS, Xcode 16+, paired developer-mode device) and routes the output to appium_session_management with action=create. It does not explicitly name when-not cases or alternatives, so it misses the top of the scale.

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