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

Annotations only say non-read-only, non-idempotent, non-destructive. The description adds meaningful behavioral detail beyond those flags: 'Files are copied in, so the originals are untouched and the simulator keeps them until it is erased.' This clarifies persistence, non-destructiveness to source files, and the fact that the simulator's library is mutated.

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 about five sentences long, but every sentence earns its place: purpose, motivation, workflow, side effects, and integration with a sibling tool. It is front-loaded with the core function and avoids filler or repetition.

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 two parameters, no output schema, and only generic annotations, the description plus schema gives an agent everything needed to select and invoke it correctly: what it does, why it exists, how to sequence it in a test flow, what side effects to expect, and how to combine it with permission handling.

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 input schema already has 100% description coverage with clear explanations for both `paths` and `device`, so the baseline is 3. The description does not add parameter-level semantics beyond the schema; it provides useful workflow context, but the schema itself carries the parameter documentation burden.

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 opens with a specific verb and noun: 'Put photos or videos into the simulator's photo library.' This clearly distinguishes it from sibling tools like screenshot, install, or launch, none of which address media seeding. It also gives the motivating problem ('A simulator has no camera'), so an agent understands exactly what unique gap this tool fills.

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 is explicit about when and how to use the tool: seed the library first, then drive the app's picker as normal. It states the consequence of not using it ('every flow that starts with an image is untestable here') and even gives complementary guidance by pairing it with `permission` on ios_simulator_set_environment to skip the access prompt.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: it reports 'both lanes separately', 'never fail[s]', and can detect a second runner by identifying which simulator owns the WDA port. This gives the agent useful expectations about reliability and output structure without contradicting the annotation.

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 dense but efficient, front-loading the core behavior ('Report both lanes separately and never fail') before enumerating the diagnostic contents. The later clauses about catching a second runner are slightly wordy but still earn their place by clarifying a key diagnostic use case.

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, the description compensates by enumerating the major output categories: existing/usable simulators, the server-selected simulator, screen geometry, and WDA port ownership. This is enough for an agent to know what to expect, though exact output formatting remains unspecified.

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 input schema already provides full coverage for the optional 'device' parameter, including guidance on omitting it and the distinction from simctl's 'booted'. The tool description itself adds no parameter-specific detail, so the high schema coverage establishes the baseline.

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 a specific action ('Report') and a concrete diagnostic resource: simulator existence/usability, server-chosen simulator, screen geometry, and WDA status with port ownership. This distinguishes it from sibling tools like ios_simulator_list or ios_simulator_restart_wda by emphasizing an aggregated diagnostic report.

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 phrase 'Start here when anything else misbehaves' provides explicit situational guidance for when to invoke this tool. It does not spell out exclusions or contrast itself against specific sibling tools, but the context is clear enough for an agent to select it as a first-line diagnostic.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description goes further by naming precisely what is destroyed (apps, data, keychain, permissions), that it is irreversible, and a non-obvious side effect: a booted simulator is shut down then re-booted because simctl refuses to erase a running one. That is real behavioral context beyond the annotations.

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?

Three sentences, zero filler, front-loaded with the destructive scope before the alternative and the mechanical side effect. Every clause carries information an agent needs.

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 destructive, two-parameter tool with no output schema, the definition is complete: safety profile (via annotations plus the description), scope of destruction, reversibility, sibling routing, and the shutdown/reboot side effect are all covered.

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 baseline is 3; the description earns an upgrade by explaining the rationale for `confirm` ('Irreversible, hence confirm') rather than just restating it. It does not add anything about `device` beyond the schema, which already documents UDID/name omission and the never-picks-arbitrarily guarantee.

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?

States a specific verb ('Wipe... back to a factory state') and enumerates exactly what is destroyed: installed apps, their data, the keychain and every granted permission. It explicitly separates itself from ios_simulator_uninstall, so an agent can route correctly without opening either schema.

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?

Names the sibling alternative and the condition that selects it: use uninstall when the goal is merely 'a first launch of one app' rather than a full reset. The irreversibility note plus the required `confirm` also tells the agent this is a last-resort operation.

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

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

Adds rich context beyond the readOnlyHint annotation: report size (tens of kilobytes), the fact that a Swift fatalError message may be absent from the report and instead appear on the app's stderr, and the summary-vs-full-report tradeoff. These are non-obvious behavioral traits an agent needs.

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?

Three sentences, each earning its place: what is returned, the cost/benefit of fetching the full file, and the fatalError caveat. Front-loaded with the core purpose.

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 single-parameter read tool with no output schema, the description covers what the summary contains, the tradeoff of the full report, and a significant real-world caveat about missing fatalError messages. No output schema exists, so the description appropriately explains what is returned.

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% and the schema's `name` description already documents the filename pattern, Retired/ subfolder behavior, and where to get the name from list_crash_logs. The description adds no parameter detail beyond the schema, so a baseline 3 is appropriate.

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?

States a specific verb and resource ('Read one simulator crash report') and enumerates what it returns: exception, termination reason, app message, top frames with resolved libraries. This clearly distinguishes it from the sibling ios_simulator_list_crash_logs, which only lists.

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?

Tells the agent to read the full .ips path only when the summary is 'not enough', implying the summary is the default. It does not name list_crash_logs as the required prerequisite for obtaining the name, though the schema's description of `name` effectively routes the agent there.

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

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

The description discloses the important overwrite behavior: installing over an existing copy replaces it and keeps its data. It also explains the misleading 'No such file or directory' failure mode for invalid builds, which is exactly the kind of context an agent needs to interpret errors correctly. This adds real value beyond the annotations.

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?

Two sentences deliver the core instruction, the key input constraint, the failure mode, and the overwrite behavior with no filler. The most important constraint is front-loaded, and every clause earns its place.

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 two-parameter install operation with no output schema, the description covers the required input shape, the common failure cases, and the side effect of reinstalling. Device-selection details are already fully specified in the schema, so nothing necessary for a correct call is missing.

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% and the schema already documents both the .app path format and the device-selection rules, so the baseline is 3. The description adds meaning by explaining that .ipa and device builds fail with a confusing error, which sharpens the agent's understanding of the path parameter beyond the schema alone.

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 opens with the specific action 'Install a build' and precisely identifies the target resource as a simulator-built .app bundle. It also clearly separates this from invalid inputs like .ipa and device builds, making the tool's purpose easy to distinguish from sibling tools such as ios_simulator_launch.

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 primary use case is explicit: install a simulator build from a .app bundle. It also gives strong negative guidance by warning that .ipa files and device builds fail. It does not explicitly name an alternative tool for launching or listing apps, but the install operation itself is unambiguous enough that no direct sibling comparison is required.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the write-and-safe profile is covered. The description adds meaningful context beyond annotations: stdout/stderr captured to files, terminate_first default behavior, OS_ACTIVITY_DT_MODE env var, and the IOS_SIMULATOR_ID/LAUNCH_ARGS environment defaults. This is richer than annotations alone.

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?

Four sentences, front-loaded with the core action ('Launch an installed app'). Each sentence delivers distinct information (env defaults, log capture, capture_logs semantics). Slight density with env-var references but no filler.

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 launch tool with no output schema, the description covers what is needed: how to pass args, where logs go, how to read them (pointing to ios_simulator_read_logs), and terminate_first behavior. Missing explicit mention of app-not-installed failure mode, but core operational knowledge is present.

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 description reinforces and contextualizes key parameters — arguments behavior (overrides env default), capture_logs purpose (Logger output to file), and the output directory context — adding narrative that links parameters to the operation's side effects.

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?

States a specific verb+resource ('Launch an installed app'), which is immediately distinguishable from siblings like ios_simulator_install and ios_simulator_terminate. It doesn't explicitly name the closest alternative (ios_simulator_terminate or ios_simulator_restart_wda), but the action is unambiguous.

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 explains how to use key features (arguments for fixture mode, capture_logs for logging) but never states when to use this tool versus ios_simulator_terminate, ios_simulator_restart_wda, or ios_simulator_open_url. Usage is implied through the feature descriptions rather than explicit routing guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses substantial behavior: unavailable simulators are filtered out, the result reports how many were omitted and how to delete them, and include_unavailable reveals them with available: false and the reason. This is rich, non-obvious behavior that an agent needs to know.

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 core purpose is front-loaded in the first sentence. The subsequent illustrative detail about typical simulators is useful context but slightly extended; it earns its place by justifying the default filtering, yet could be trimmed without losing essential guidance.

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?

Despite lacking an output schema, the description covers the essential return values: UDID, available flag, reason, and count of excluded simulators. It also explains the default filtering and how to opt into seeing unavailable ones, making the tool self-sufficient for an agent to invoke 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 coverage is 100%, so the baseline is 3. The description adds extra meaning for include_unavailable, explaining the returned available: false flag and the reason, which goes beyond the schema. booted_only and name_contains are already well documented in the schema, so no further elaboration is needed.

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 'List the simulators on this machine' and highlights the key output, the UDID, which every other tool consumes. This distinguishes it from sibling tools like ios_simulator_list_apps, which lists apps rather than simulators.

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 clear context: it shows usable simulators by default, and explains when to use include_unavailable to understand why a simulator is missing. It implies this is the tool to obtain a UDID for other tools, though it does not explicitly name alternatives or state 'use this before X'.

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

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

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: results are filtered to the user's own apps by default, stock simulators contain about thirty apps, and each entry exposes a real filesystem path in dataContainer that enables direct reads. This is rich, non-obvious context that helps an agent trust and interpret the result.

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?

Three sentences with no filler: the main purpose is front-loaded, followed by high-value behavioral details and a practical note about dataContainer. Every sentence earns its place.

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 read-only listing tool with two optional parameters and no output schema, the description plus schema fully cover how to invoke it, what the output will contain, and how to use the returned values. Nothing essential is missing.

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 already documents both parameters fully, including the device ambiguity rule and include_all default, so the description does not need to add parameter-level detail. The description's 'Defaults to your own apps' reinforces include_all but adds little beyond the 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 states a specific action and resource: 'List the apps installed on a simulator', and immediately adds the key value proposition that it returns the bundle id used by other tools. This clearly separates it from sibling tools like ios_simulator_list and ios_simulator_ui_tree.

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?

It gives practical context for when to use the tool: to obtain bundle ids that other tools consume, and it explains the default filtering behavior. It does not explicitly name an alternative or state a when-not-to-use condition, but the purpose is so distinct that the omission is minor.

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

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

Annotations only cover readOnlyHint, so the description carries real behavioral weight: it explains where reports physically live (~/Library/Logs/DiagnosticReports), that output is filtered to simulators only and labeled by simulator, and that no boot is required. It also flags the non-obvious defaulting difference (device does not default to booted) — genuinely useful context beyond the annotations.

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?

Front-loaded with the core action, then layered with the most decision-relevant facts in a compact sequence. Every sentence earns its place; no filler or restatement of the name.

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 read-only list tool with no output schema, the definition supplies the location of the data, the filtering semantics, the follow-up tool, and the boot precondition — everything an agent needs to call it correctly and interpret the results.

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 all four parameters, and the description mainly echoes `process`. However it adds interpretive value the schema lacks — that most results are system daemons, so `process` is the practical filter for finding your own app's crash.

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?

States a specific verb and resource ('List crash reports from simulator processes'), immediately scoping to simulators and ordering 'newest first'. It clearly distinguishes itself from the sibling ios_simulator_get_crash_log, which it names for reading individual reports.

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?

Gives concrete selection guidance ('pass `process` to find your app's') and routes the agent to the right sibling for the follow-up action. It also states an important precondition contrast ('Nothing needs to be booted'), though it does not explicitly exclude versus sibling listers like ios_simulator_read_logs.

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

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

Annotations are neutral (no readOnly/destructive hints), so the description carries the behavioral burden. It discloses non-obvious routing behavior for https vs custom schemes, which is valuable context beyond what annotations provide.

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?

Two tight sentences: the first front-loads the purpose, the second adds a key behavioral detail. No filler or repetition of schema content.

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 two-parameter tool with no output schema, the description plus detailed parameter schema covers purpose, usage context, scheme behavior, and device selection. Nothing needed for a correct call is missing.

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 baseline is 3. The description adds extra meaning by explaining how the URL's scheme affects behavior, helping an agent choose an appropriate value beyond the schema's examples.

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?

States the exact action ('Open a URL on the simulator') and the purpose ('exercise a deep link or a universal link'), immediately distinguishing it from tap-based sibling tools. The additional scheme-routing details further clarify what the tool does.

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 provides a clear use case: when you need to exercise a deep/universal link without tapping one. It implies this tool overrides manual tapping but does not explicitly name alternatives or exclusions, so it misses a fully explicit routing statement.

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

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

Annotations declare idempotentHint=true and readOnlyHint=false, but the description adds real behavioral context the annotations cannot: a cold boot takes tens of seconds, puts a window on the user's screen, and shifts which simulator an unqualified call resolves to. Idempotency is restated with concrete detail (booting a booted simulator succeeds), which reinforces rather than merely repeats the annotation.

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?

Three sentences, front-loaded with the core action and each clause carrying distinct information (latency, user-visible side effect, resolution side effect, idempotency). The em-dash construction makes it slightly dense but nothing reads as filler.

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 four fully documented parameters, idempotency annotations, and no output schema, the description covers the operationally risky facts an agent needs: latency, window visibility, and post-boot resolution changes. Only minor gaps remain around failure/timeout behavior, which is partly addressed by wait_ms in the schema.

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 description adds one genuinely non-schema nuance — that the boot changes what an unqualified call resolves to — but it does not describe the `state`, `wait_ms`, or `open_window` parameters, leaving the schema to carry that load.

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?

States a specific verb pair and resource: 'Boot or shut down a simulator.' This is immediately distinguishable from siblings like ios_simulator_erase, ios_simulator_install, and ios_simulator_launch, which mutate content rather than power state.

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?

Explains when this tool is mandatory ('Booting is the one thing this server will not do for you implicitly'), which tells the agent it must call this before other tools can work on a fresh device. It does not explicitly name alternatives or state when-not-to-use beyond idempotency, so it falls short of a 5.

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

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

Annotations only supply readOnly/idempotent/destructive hints; the description adds the key behavioral consequence that home backgrounds the app without terminating it, and the schema notes that home is a gesture on Face ID devices. It does not contradict the annotations and gives useful behavioral context beyond the structured hints.

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 two short sentences with the verb and resource front-loaded and the most useful guidance in the second sentence. There is no filler or repetition of what the schema already states.

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?

Given the rich per-parameter descriptions, the annotations, and the simplicity of the action, an agent has enough to select and invoke the tool correctly. The lack of an output schema is mitigated by the screenshot parameter explicitly describing the returned screenshot behavior.

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 tool description adds value by explaining what the `home` parameter accomplishes (returning home/backgrounding without termination). The remaining parameters are already richly described in the schema, including device-selection behavior and settle_ms semantics, so the overall parameter guidance is strong.

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 states a concrete action ('Press a hardware button') and immediately explains the purpose of the only supported button: returning to the home screen and backgrounding the app without terminating it. This clearly differentiates it from terminate, launch, screenshot, and other simulator actions.

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?

It gives clear when-to-use context: use home to go back to the home screen or to background the app safely without terminating it. The settle_ms parameter description further routes longer waits to ios_simulator_wait_for_element, but the prose does not enumerate exclusions for every sibling, so it stops short of a 5.

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

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

Annotations only provide readOnly/idempotent/destructive hints, so the description carries most of the burden. It discloses the simulated nature, the payload requirement to contain an 'aps' key, and the fact that the app need not be running. It stops short of describing the visible result or any permission behavior, but the core behavior is clear.

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?

Three dense sentences with no filler. Each clause adds a necessary constraint or limitation, and the most important scoping information is front-loaded.

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 3-parameter action with a nested payload and no output schema, the description plus schema gives the agent everything needed to invoke it correctly: device selection behavior, payload format and size, bundle id pattern, and push-type restrictions. No critical selection or invocation information is missing.

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 baseline is 3, but the description adds semantic value beyond the schema: it requires the payload to be a 'normal remote-notification body' containing an 'aps' key. The schema already covers device selection rules, the payload example, byte limit, and bundle id pattern.

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 starts with a specific verb and resource: 'Deliver a push notification' to the iOS simulator. It immediately distinguishes this tool from real APNs delivery by adding 'with no APNs certificate and no server,' and no sibling tool performs push, so there is no ambiguity.

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?

It gives a clear context for use: simulator push testing without needing APNs infrastructure. It also states explicit exclusions ('not VoIP, complications or file-provider') and prerequisites ('The app must be installed; it does not have to be running'), though it does not name alternative tools.

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

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

Annotations only assert readOnlyHint=true, but the description discloses the capture lifecycle ('capturing turns false once the app's process has exited, and what it wrote stays readable') and the crash-content boundary (backtrace excluded, fatalError included). This is substantial behavioral context beyond the safety profile.

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?

Front-loaded with the core capability, then preconditions, then return contract, then boundaries. Every sentence carries distinct information — the crash-log routing and the capture-persistence note are not padding.

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, the description carries the return contract itself: newest `limit` lines plus a `next` cursor. Combined with the precondition and the crash-log boundary, an agent has everything needed to call and interpret this tool 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 100%, so the baseline is 3, but the description adds integration semantics: the cursor is described in terms of the incremental workflow, filter is noted effectively in the 'see what one tap logged' framing, and the device-omission rule is reinforced. It stops short of restating every field, which is appropriate given the schema already covers them.

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?

States a specific verb and resource ('Read an app's log output') and enumerates exactly what is captured: stdout, stderr, and Logger/os_log messages interleaved. It also distinguishes itself from the sibling ios_simulator_list_crash_logs, so an agent can route correctly without opening either schema.

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?

Gives an explicit precondition ('Only available for an app started with ios_simulator_launch capture_logs: true'), names the crash-log tool as the alternative for backtraces, and explains the incremental-read pattern ('pass it back to get only what arrived since'). When-to-use, when-not-to-use, and the alternative are all covered.

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

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

Beyond the annotations, the description discloses key behavioral traits: the runner is started detached, it outlives the conversation, output goes to a log file, and it does not wait. This is exactly the kind of context an agent needs to use the tool correctly and verify success.

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?

Four sentences, each earning its place: purpose, scope, runtime behavior, and verification step. The description is front-loaded with the core function and avoids fluff or repetition.

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 side-effecting tool with no output schema, the description covers what the tool does, when to use it, what side effects to expect, how long to wait, and where to check results. That is sufficient for an agent to invoke and verify 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?

The tool description itself does not add parameter-level meaning, but the input schema provides 100% coverage with detailed descriptions for both `port` and `device`. Baseline 3 is appropriate because the schema already carries the semantic weight.

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 a specific verb and resource: 'Start the WebDriverAgent runner, or restart it after it has died.' It clearly differentiates from siblings by stating that only UI tree and input tools need it, while screenshots and simctl operations do not.

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 when this tool is needed and when it is not: 'Only the UI tree and the input tools need it.' It also gives the follow-up action ('check ios_simulator_diagnostics') and a timing expectation, which is strong practical guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses the key behavioral traits: default scaling to device point size, the resulting coordinateSpace metadata ('points'), the shift to image_pixels when max_dimension is overridden, and the fact that save_path writes a full-resolution PNG while 'the returned image is still the downscaled one.' This is exactly the kind of non-obvious behavior an agent needs to interpret results correctly.

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?

Four sentences, each earning its place: core purpose, the critical coordinate-space behavior, sibling complementarity, and workflow rule. The most decision-relevant fact (tap-coordinate compatibility) is front-loaded in sentence two. No filler, no repetition of schema content.

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?

Despite having no output schema, the description conveys the return semantics that matter (image plus coordinateSpace metadata), and the schema handles the four optional parameters exhaustively. The readOnly annotation covers the safety profile. Nothing an agent needs to invoke this correctly — coordinate systems, sibling relationships, workflow cadence, parameter trade-offs — is missing.

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 baseline is 3 — and indeed the schema's per-parameter descriptions are rich on their own. The main description adds one genuinely additive semantic: the default scaling means 'a position read off this image can be passed straight to ios_simulator_tap with no conversion,' which gives the default parameter behavior a concrete cross-tool consequence not stated in the schema. This nudges it above baseline.

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 states a specific verb and resource — 'Capture the screen and return it as an image' — and immediately distinguishes itself from the closest sibling, ios_simulator_ui_tree: 'the image shows you what the screen looks like, the tree gives you exact labels and identifiers.' An agent can tell exactly what this tool does and how it differs from alternatives.

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 explicit pairing guidance: 'Pair it with ios_simulator_ui_tree rather than choosing between them,' complete with the reason for each tool's role. It also prescribes a workflow rule ('Re-screenshot after every action rather than chaining blind taps') and the device parameter description further advises when to omit it. This is actionable usage direction, not just a vague context hint.

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

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

With annotations already marking the tool as non-read-only, idempotent, and non-destructive, the description adds important behavioral context beyond the annotations: fields are applied in order, the result reports the resulting state, and status bar overrides persist across reboots and can pollute later screenshots if not cleared. This is genuinely useful operational warning.

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 compact and front-loaded. The first sentence states purpose and lists capabilities; the second justifies simulator preference; the third explains optionality and ordering; the fourth warns about persistence. Each sentence earns its place without redundancy or fluff.

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 complex 9-parameter tool with no output schema, the description covers the essential invocation semantics: optional fields, application order, state reporting, and the key persistence caveat. It doesn't detail what 'reports the state afterwards' includes, but given the strong schema coverage, this is complete enough for an agent to select and invoke the tool 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 100%, so the baseline is 3. The description adds value by summarizing the parameter groups and by stating two cross-cutting facts not in the schema: every field is optional, and provided fields are applied in order. This helps an agent understand interactions between parameters like clear_location and location.

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 opens with a specific verb-resource pair: 'Stage the simulator before a screenshot or a test' and then enumerates the exact capabilities (dark mode, Dynamic Type, increased contrast, frozen status bar, simulated location, app permissions). This clearly distinguishes it from sibling tools like screenshot, tap, or launch, which do different jobs.

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 clear usage context: use this tool to prepare state before screenshots or tests. It also explains why simulator-only features matter for UI work. It does not explicitly name alternatives or exclusion conditions, but no sibling tool offers equivalent functionality, so the guidance is sufficient.

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

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

Beyond the minimal annotations, the description discloses that duration_ms distinguishes a controlled scroll from a momentum fling, and that short drags 'throw the list past where you aimed.' This adds meaningful behavioral context. No contradiction with annotations.

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?

Three sentences, each earning its place: the core action, the practical direction mapping, and the duration behavior. The most important conceptual guidance is front-loaded.

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, combined with the richly documented 100% schema coverage, gives an agent everything needed to invoke the tool correctly. No output schema exists, but returning a screenshot is handled by the screenshot parameter, which is already documented.

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 baseline is 3. The description adds value by explaining the direction-to-screen relationship and the semantic difference between scroll and fling via duration_ms, which enriches the raw parameter meanings.

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 opens with a concrete action and object: 'Drag from one point to another, in points.' It then names real user goals — scroll a list, pull to refresh, swipe a row open — which clearly separates it from sibling tap and type tools.

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?

It gives explicit guidance for when to use the gesture, including how to scroll down and what duration produces a fling. It does not explicitly name alternatives or state when not to use it, but the use cases are clear enough for an agent to select it.

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

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

Annotations only carry readOnly/destructive/idempotent hints, all false, so they don't reveal failure modes. The description adds meaningful behavioral context: coordinate taps silently break after layout changes and 'nothing about a wrong tap looks wrong.' This is the kind of behavioral warning that helps an agent decide between coordinate and element taps.

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?

Three dense sentences each carry distinct value: what the tool does, when not to use it, and how coordinates are sourced. The warning is front-loaded right after the purpose, before any lower-priority detail.

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 plus fully documented input schema give an agent everything needed to select and invoke the tool correctly: purpose, coordinate space, failure mode, and parameter semantics. It stops short of explicitly describing the return value beyond the screenshot parameter, but the schema already covers that detail.

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?

Input schema covers 100% of parameters with detailed descriptions, including units, defaults, and distinctions like 'pause for animation, not wait for work.' The description reinforces the coordinate-space relationship, but does not need to compensate for schema gaps because none exist.

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?

States a precise verb and object — 'Tap a position on screen, in points' — and immediately differentiates itself from ios_simulator_tap_element by naming the condition under which the element-based sibling should be preferred. The coordinate-source sentence also anchors exactly what the tool acts on.

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?

Gives explicit routing guidance: prefer ios_simulator_tap_element when the target has a label or accessibility identifier, with a concrete reason (layout shifts make coordinates stale). It also tells the agent where coordinates come from — default screenshot or ui_tree tap field — closing the main usage ambiguity.

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

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

It discloses useful behavioral traits beyond annotations: the device resolves the element's position, and the approach is robust to scrolling, layout changes, and reworded copy. Annotations only cover read-only/idempotent/destructive hints, so this extra context genuinely helps an agent predict behavior.

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?

Three short sentences with no filler: the core action comes first, followed by the rationale and the essential param rule. The 'identifiers from ios_simulator_ui_tree' note is compact and useful.

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 7-parameter action tool with no output schema, the description covers the main decisions an agent must make: which selector to use, where identifiers come from, and how this differs from coordinates. The screenshot parameter description already clarifies the output expectation, though the description itself could have mentioned what happens on no-match or multiple-match cases.

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 already documents all 7 parameters thoroughly, so this dimension starts near baseline. The description adds a key semantic constraint not enforced by the schema: exactly one of id, label, or predicate must be provided, and it points to ios_simulator_ui_tree as the source of identifiers.

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 and object: tap an element by accessibility identifier or label. It also contrasts itself with coordinate-based interaction, signaling clearly that this is the element-aware counterpart to ios_simulator_tap.

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 frames this as 'the tool to reach for' when the element may move or the text may change, and explains why it beats coordinate-based taps. It does not name ios_simulator_tap or list exclusions, but the usage context is clear and actionable.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false, and the description adds meaningful context: the app is not uninstalled, its data remains intact, and the result is a cold start. This goes beyond the structured hints without contradicting them.

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 sentence with no filler. It front-loads the core action, then immediately states the key behavioral nuance (no uninstall, data untouched) and the practical purpose (cold start).

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 simple two-parameter kill operation, the description plus schema and annotations cover what an agent needs: required bundle_id, optional device selection guidance, non-destructive behavior, idempotency, and the use case. No out-of-schema return format is necessary for a command like this.

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 input schema already documents both parameters fully, so the baseline is 3. The description adds value for the optional device parameter by explaining when to omit it, how IOS_SIMULATOR_ID applies, and that it avoids simctl's arbitrary selection behavior, which helps an agent pick the right value.

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 states a specific action ('Kill a running app') and a clear resource, and goes beyond a simple restatement of the title by explaining what it does not do: it does not uninstall the app and does not touch its data. This distinguishes it from destroy/erase-style operations, and 'back to a cold start without erasing anything' sharpens the intended effect.

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 a clear context for use: when you want a cold start without erasing app data. It implicitly contrasts with uninstall/erase operations, though it does not explicitly name an alternative sibling tool or say when not to use it.

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

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

Beyond the annotations, it discloses the important silent-success trap: with no focus, keystrokes go nowhere but the call still succeeds. It also explains that id/label trigger a pre-tap. It does not cover what happens if the named field is not found, but the core behavioral risk is clearly exposed.

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 main description is two tight sentences with the most important caveat (focus trap) front-loaded. Every sentence carries load, and the parameter descriptions handle the remaining detail without bloating the main description.

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 schema covers all seven parameters, including device selection, screenshot behavior, settle semantics, and clear_first constraints, so an agent has most of what it needs. Missing top-level detail about return shape and invalid-identifier behavior is a minor gap given no output schema, but the overall definition is still quite complete.

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 description adds meaningful cross-parameter semantics by explaining that id/label are how the caller ensures focus, and it ties clear_first to the presence of id/label. This goes beyond the simple field-level descriptions in the 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 opens with a specific verb and resource: typing text into the current keyboard focus or a named field. It also explains the two ways to target input, which distinguishes it from the tap-oriented siblings and makes the tool's job immediately clear.

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?

It gives an explicit usage rule: pass id or label to tap the field first unless a field is already active, and warns against relying on focus when nothing is focused. It does not name alternative sibling tools in the main description, though the settle_ms parameter does direct longer waits to ios_simulator_wait_for_element.

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

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

Beyond the readOnlyHint annotation, the description reveals important behavioral traits: results are flattened, the raw hierarchy is tens of KB, defaults return only controls, the `filtered` field counts omissions, and coordinates are in the same point space as ios_simulator_tap. It also warns that `include_invisible` is not always truthful, which is valuable non-obvious behavior.

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?

Every sentence earns its place: purpose, comparison to screenshots, default behavior, filtering guidance, and coordinate-space note are all packed into a compact, front-loaded description with no filler.

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?

Despite having no output schema, the description explains what elements contain, how filtering affects results, what the `filtered` field means, and how coordinates relate to tapping. For a read-only inspection tool with this parameter richness, the description gives an agent enough context to invoke it correctly and interpret results.

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 baseline is 3. The description adds practical parameter semantics by explaining how to narrow (`contains`, `types`) and widen (`detail`), and by tying the coordinate output to ios_simulator_tap's input space. This goes beyond merely restating the 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 opens with a specific verb and resource: 'List the addressable elements on screen — type, label, accessibility identifier, and the exact point to tap — flattened rather than nested.' It clearly differentiates the tool from screenshot-based inspection by explicitly saying to prefer this over reading coordinates off a screenshot.

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?

It gives explicit when-to-use guidance: 'Prefer this over reading coordinates off a screenshot whenever you can: a label or identifier survives the screen moving, and a pixel position does not.' It also advises how to narrow or widen results with `contains`, `types`, and `detail`, and warns to check `filtered` before concluding the screen is empty.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds substantive context beyond them: what exactly is destroyed (documents, databases, preferences, 'nothing brings them back'), and the non-obvious behavioral quirk that uninstalling a missing app still succeeds, so success is not proof of prior presence. That last detail is a real edge case an agent could otherwise misinterpret.

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?

Three sentences, each earning its place: destruction scope, cold-start alternative, narrower vs erase, and the success-flag caveat. Front-loaded with the destructive consequence rather than burying it behind pleasantries.

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 destructive mutation tool with no output schema, the description supplies the critical missing semantics: what is destroyed, alternatives for different intents, and the false-success edge case. Annotations cover the safety flag, schema covers parameters, and the description covers behavior and routing — nothing material is missing.

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 all three parameters thoroughly (device omitting behavior, confirm must be true, bundle_id pattern and examples). The description adds no parameter syntax beyond the schema. Baseline 3 is correct when the schema fully carries parameter documentation.

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?

States a specific verb+resource (remove an app from the simulator) and immediately differentiates scope ('with its data container', narrower than erase). It explicitly names sibling tools (terminate, erase) with their distinguishing scope, so an agent can route correctly without opening schemas.

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?

Explicitly provides when-to-use and when-not: 'to get back to a cold start while keeping the data, use ios_simulator_terminate' and 'to test a genuine first launch of one app, this is narrower than ios_simulator_erase, which wipes every app'. This is direct routing to alternatives with conditions.

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

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

readOnlyHint=true already covers the safety profile, and the description earns substantial credit beyond it: the warning that an MCP client's own request timeout "will cut this call off before timeout_ms does," the polling semantics, and the "give exactly one of" constraint. No contradiction with the annotation — polling and observing are inherently non-destructive.

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?

Three sentences with purpose front-loaded in the first clause, and every sentence earns its place: the settle_ms exclusion prevents a common misuse and the client-timeout note is a necessary caveat. It is dense, with the timeout caveat arguably better placed after the parameter rule, but there is no waste.

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 an 8-parameter polling tool with no output schema, the description covers purpose, use cases, exclusions, parameter exclusivity, and an external failure mode. The remaining gap is the return contract — nothing states what a timeout or successful wait returns beyond the optional screenshot — but this is minor and largely inferable from the polling semantics.

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% and every parameter carries a rich description, so the baseline is 3. The description adds a genuinely non-derivable constraint — "Give exactly one of id, label or predicate" — and points to ios_simulator_tap_element as the convention reference, which raises it above baseline.

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?

States a specific verb and resource in the opening clause — "Poll until an element appears, or until it goes away" — covering both wait directions immediately. It positions itself as "the tool for a screen that loads" and explicitly contrasts with the settle_ms pause on action tools, so an agent can tell it apart from the tap/action siblings without inspecting schemas.

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?

Gives explicit when-to-use context ("a generation step, a network round trip, a long import") alongside an explicit when-not-to: settle_ms "caps at ten seconds — it is not a wait, and using it as one is how you end up verifying a server instead of the screen." It names the alternative pattern it is not, which is the strongest possible routing guidance.

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