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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the press does not activate the session app, that nothing is re-observed so state is preserved, that the system's response is not observed, and that the command times out after 90 seconds. This is unusually thorough.

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 three focused sentences with no filler. The core action is front-loaded, followed by the most important behavioral caveat and the timeout. Every sentence adds 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?

The tool has no annotations but has a rich input schema and an output schema. The description covers the essential non-obvious runtime behavior: side-effect scope, observation behavior, simulator limitations, verification constraints, and timeout. Nothing critical is missing for correct invocation.

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 applies: the schema already explains every parameter. The description adds no parameter-specific guidance, which is acceptable because the structured schema does the heavy lifting.

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: 'Press the iPhone or iPad Action Button once.' It also differentiates the action from generic siblings by noting the press is dispatched without activating the session app and that nothing is re-observed afterwards, making the tool's scope unmistakable.

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 for when the tool is meaningful, notably that delivery to a Shortcut is verifiable only on a physical iPhone and that simulators run no Shortcuts or App Intents. It does not explicitly name alternative sibling tools or state 'use this instead of X', but the practical when/when-not context is present.

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 no annotations provided, the description carries the full burden and does so: it discloses state mutation, per-execution activation limits on iOS XCTest (activates once, then only observes), label preference ordering, refusal semantics for equal-ranked or unknown labels, the ALERT_BUTTON_NOT_FOUND result with "having tapped nothing," and a 90s timeout. These are exactly the non-obvious traits an agent could not infer from the 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?

Purpose and the read-before-mutate rule are front-loaded, then platform-specific detail follows in a logical order (iOS XCTest, then Apple XCUITest runner, then failure handling, then timeout). It is dense and long, but nearly every sentence carries operational information; the label enumeration is the only mildly padded stretch.

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, platform-divergent tool with 18 parameters, no annotations, and no output schema, the description covers action semantics, per-platform matching rules, and failure modes thoroughly. The remaining gap is return-shape information — what alert get actually yields and what wait returns versus timing out — which the agent must infer.

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 89%, so the schema already documents nearly every parameter and baseline is 3. The description adds only a little parameter-level meaning: the four action verbs are described in prose and the 90s timeout implicitly documents the otherwise undescribed timeoutMs. Device-resolution parameters (udid, serial, device, platform, target) get no treatment 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?

Opens with a specific verb set and resource: "Inspect, wait for, accept, or dismiss a platform alert," which maps directly onto the four action enum values and distinguishes it from generic interaction siblings like click or find. It also immediately flags which of those verbs mutate state ("accept and dismiss change the active alert 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?

Gives explicit sequencing rules ("Use get before acting when the alert content matters," "Inspect again after an unconfirmed action") and an explicit fallback path when the built-in label matching fails: read labels with alert get, then press the button by label. It also states when not to assume success ("never assume a timeout means nothing happened").

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 no annotations provided, the description carries the behavioral burden; it does disclose a 90s timeout, which is useful operational context. However, it does not state side effects, default filtering behavior, or failure modes beyond the timeout, and the system/OEM sentence reads more like policy than 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?

Two sentences, front-loaded with the action, then a scoping rule and timeout. There is no filler; 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?

Given the output schema and 100% parameter coverage, the description does not need to explain return values or selector semantics. It includes the non-obvious operational constraint (90s timeout) and the policy on system/OEM apps, which is sufficient for a low-complexity listing tool.

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 schema fully documents all 16 parameters; the description does not need to repeat parameter details. It adds only the system/OEM condition, which overlaps with the appsFilter parameter rather than extending its meaning.

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 apps installed on the selected device.' This clearly distinguishes the tool from siblings like install, appstate, and snapshot. The system/OEM qualification adds scope without obscuring the core purpose.

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 conditional usage hint—include system/OEM apps only when they are needed as automation targets—but does not name alternative tools or state when not to use this one. The guidance is implied rather than explicit, so an agent must infer that apps is for enumeration before automation.

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 no annotations, the description carries full burden but does disclose two useful traits: a 90s timeout and the platform-dependent answer semantics (Android/HarmonyOS direct vs iOS/macOS per session). It does not state read-only safety or what happens on timeout, so the disclosure is partial.

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 compact clauses, front-loaded with the core action and immediately qualified by platform and timeout. Minor flaw: the two sentences run together without punctuation after the closing parenthesis, slightly harming readability.

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?

An output schema exists, so return values need not be explained, and the description covers the key operational caveats (platform scope, 90s timeout). For a zero-required-param query tool this is largely sufficient, with only the read-only/timeout-behavior detail 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 description coverage is 100%, so all 15 device-selection and output-shaping parameters are already documented in the schema. The description adds nothing about params, which is acceptable given the schema does the heavy lifting.

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: 'Show foreground app/activity', with platform scope parenthetically qualified (Android/HarmonyOS direct; iOS/macOS per session). It is distinguishable from query siblings like apps/get, though it never names them explicitly.

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?

There is no when-to-use guidance and no alternatives named. An agent must infer that this is the read for current foreground state versus siblings such as apps, is, snapshot, or session, which is a plausible confusion in this crowded sibling set.

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 no annotations provided, the description carries the disclosure burden. It honestly warns that the tool 'changes the visible system UI,' 'may move focus away from the current app,' and 'times out after 90s.' These are the key behavioral side effects an agent should know before invoking the tool.

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: purpose first, then the key side effect, then the timeout. Every sentence provides necessary information and there is no filler or redundancy.

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?

An output schema exists, so return-value details are not needed in the description. The description gives the essential behavioral context: it changes system UI, may move focus, and times out. It is sufficient for a safe call, though it could also have pointed to sibling alternatives.

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 description coverage is 100%, so all 16 parameters are already documented in the input schema. The description adds no parameter-level detail, and the baseline of 3 is appropriate because the schema does the semantic heavy lifting.

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 identifies the action and resource: 'Open the device app switcher.' It also states the purpose ('inspect or change foreground apps'), which makes the tool's intent understandable. It does not explicitly distinguish itself from sibling tools like apps, open, or focus, so it misses top marks.

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 intended use is implied by 'to inspect or change foreground apps,' but there is no explicit guidance about when to use this tool versus siblings such as focus, open, or apps. An agent must infer the appropriate context rather than being told directly.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses a 90s timeout, which is genuine behavioral context, but says nothing about permissions, whether listing is read-only, pagination, or what an artifact actually is. Partial disclosure only.

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 short sentences with zero waste; the core action is front-loaded and the timeout caveat follows immediately. Nothing redundant.

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 17 parameters, no annotations, and no output schema, the description is thin. Because no output schema exists, the description should explain the return shape or artifact types, and it instead only names the timeout, leaving the agent unclear on what it will actually receive.

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% across all 17 parameters, so the schema fully documents selectors (udid, serial, session, providerSessionId, runId, etc.). The description adds no parameter-level meaning beyond that, which is the baseline 3 when the schema does the heavy lifting.

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 (List) and resource (daemon or cloud provider artifacts) scoped to an active or completed session. It is clear what the tool does, though 'artifacts' is left undefined and it never distinguishes itself from siblings like logs or screenshot that also surface session output.

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 'for an active or completed session' implies a session prerequisite, but there is no explicit when-to-use, when-not-to-use, or comparison against alternatives such as logs, snapshot, or screenshot. An agent must infer the selection condition entirely.

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 no annotations provided, the description carries the full behavioral disclosure burden. It discloses three important behaviors: the stateful probe lifecycle, the need to start before status/stop, and the 90-second timeout. This is meaningful operational context beyond what the schema alone provides.

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 with no fluff. The primary purpose is front-loaded, and the lifecycle constraint and timeout are stated concisely. Every sentence adds useful information.

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 the core operation and lifecycle, but the tool has 19 parameters, no required parameters, no output schema, and no explanation of how durationMs and bucketMs interact. Common selectors are documented in the schema, but an agent still lacks clear guidance on the minimal invocation or expected structured response.

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 high at 89%, so the baseline is 3. The description adds value beyond the schema by explaining that 'start', 'status', and 'stop' correspond to probe lifecycle phases, and by framing outputs as 'dBFS buckets,' which gives meaning to bucketMs and durationMs.

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: 'Measure browser or host-rendered simulator/emulator audio as compact dBFS buckets.' This clearly defines what the tool does and the output format, making it distinguishable from sibling tools like record or logs.

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 lifecycle guidance: 'Start a probe before requesting its status or stopping it.' This tells the agent the correct order of operations. It does not mention alternative tools or when not to use audio, but the core usage context is clear.

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 no annotations at all, the description carries the full burden and mostly succeeds: it discloses the 90s timeout, that a caller-supplied budget extends it, and the significant failure semantics that a capture failure yields an unknown outcome rather than a clean error. It also documents the top-leading tap workaround with before/after visual verification. It does not state auth/permission requirements or whether the action is recorded, though the schema's noRecord parameter partly covers the latter.

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?

Five tight sentences, purpose front-loaded before the mode guidance and edge cases. Minor waste in "a caller-supplied budget extends it", which never names which parameter carries that budget, leaving the reader to hunt through twenty fields.

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?

An output schema exists, so return values need no explanation, and the timeout/failure behaviour is covered. However, for a twenty-parameter tool with zero annotations and no required fields, an agent still lacks guidance on the device-selection parameters (udid vs serial vs device vs session) and on whether this action is recorded or requires an existing session/lease.

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 95%, so the baseline is 3 and the schema already documents the twenty parameters in detail. The description adds genuine meaning for mode beyond the bare enum (which stack each value targets), which earns it the top of the baseline rather than above it — the remaining nineteen device/lease/response parameters are left entirely to 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?

States a specific verb plus resource ("Navigate back") and immediately disambiguates the two modes it can take. It does not explicitly contrast itself with near neighbours like home, app-switcher, or hardware-button, so an agent must infer that this is the in-app history pop rather than a system-level exit, but the core 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?

"Use in-app for the app navigation stack and system when the platform back behavior is required" is a real selection rule for the mode parameter, and the single-screen iPhone note gives a concrete fallback condition. What is missing is a negative rule — when not to use this and to reach for home, app-switcher, or press instead.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses only the single-request execution model and 90s timeout, omitting execution ordering, failure semantics, side-effect risks of nested commands, and response 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?

Two short, front-loaded sentences with no repetition or filler. The timeout note is useful and 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?

This is a complex batch tool with many parameters, a large nested command enum, and no output schema. The rich schema covers parameter details adequately, but the description leaves important batch execution and response semantics unexplained.

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 schema already documents all 19 parameters. The description adds no parameter-level meaning beyond the general idea of running multiple commands.

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: executing multiple commands in one daemon request. This distinguishes the batch tool from individual command siblings, though it does not explicitly name those 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 batching use case is implied by 'multiple commands in one daemon request,' but there is no explicit guidance on when to use this instead of separate command calls, nor any exclusions or prerequisites.

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 no annotations, the description carries the full disclosure burden. It usefully reveals a 90s default timeout and that a caller-supplied budget extends it, plus the device-selection rule, but says nothing about idempotency (behavior if already booted), failure modes, or permission/auth requirements.

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 tight sentences, front-loaded with purpose, then the selection rule, then the timeout constraint. Every sentence carries new information and none is redundant with the schema or 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?

An output schema exists, so return values need not be explained, and the description covers purpose, selection, and timeout. It leaves minor gaps around idempotency and failure behavior for a no-annotation tool, but nothing that would prevent correct invocation.

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% (baseline 3), and the description adds a non-obvious cross-parameter rule: target device selection flows through the selector inputs rather than a name argument, and timeoutMs acts as an extendable budget. That is meaningful guidance beyond the schema text.

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 (boot/prepare) and resource (device or simulator) plus the downstream purpose ('so later commands can target it'), so an agent understands it is a setup/readiness step. It does not explicitly distinguish itself from siblings like shutdown or install, but the semantics are 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?

Gives clear context ('so later commands can target it') and an explicit usage rule: the device is chosen through device-selection inputs, not by naming it here. It stops short of naming alternatives or when-not-to-use conditions (e.g., what to do if already booted).

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It usefully notes the 90s timeout and distinguishes device-based vs active-session operation, but it does not mention whether the command is read-only, has side effects, or what failure modes to expect.

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 carry the core purpose, the key usage context, and a critical timeout warning. Every sentence earns its place and the most important 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?

Given the tool's 15 optional parameters, no annotations, and no output schema, the description covers the central usage but leaves the agent to infer return shape and how multiple selectors like udid, session, leaseId, and runId interact. The 100% schema coverage compensates substantially, but some contextual gaps remain.

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 covers all 15 parameters, so the baseline is 3. The description adds cross-parameter context by advising to use device-selection inputs before a session is open, which is not stated in the schema itself.

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 clear action and resource: 'List the commands supported by the selected device or active session.' It communicates the tool's function specifically, though it does not explicitly distinguish it from the sibling 'help' tool or other listing-style commands.

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 concrete context: 'Use device-selection inputs when checking support before a session is open.' This tells the agent which parameter family to use in a common scenario, but it does not mention exclusions or explicitly contrast with alternatives like 'help'.

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 no annotations, the description carries the full burden and does: it discloses state mutation ('can change app state'), the critical dispatch-vs-landed success semantics, the motion re-check and the `target_still_moving` refusal, and a 90s timeout that a caller budget can extend. These are non-obvious runtime behaviors an agent could not infer from schema or 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 action and its targeting modes, then preference, then consequences. Every sentence carries distinct information; the only slight cost is the densely packed motion-detection sentence, which is valuable but reads as a run-on.

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 tool is definitionally simple but has 29 parameters and a real timing/safety surface; the description covers the parts an agent would otherwise get wrong (targeting choice, success ambiguity, motion refusal, timeout). An output schema exists, so return-shape explanation is correctly omitted.

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 baseline is 3; the description earns more by explaining semantics the schema only labels — what `settle`/`verify` are for as substitutes for a follow-up snapshot, and how `timeoutMs` relates to the fixed 90s ceiling. It adds no extra detail on the device-selection or repetition parameters, which is acceptable given the schema 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 ('Activate a UI target') and enumerates the three targeting modes (snapshot ref, selector, coordinates), which lets an agent map the `target` union immediately. It does not distinguish itself from near-siblings like `press`, `longpress`, or `hover`, so the differentiation is incomplete.

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 preference ordering — ref or selector after a snapshot, coordinates only when semantic targeting is unavailable — plus guidance to use settle/verify or a screen wait instead of a follow-up snapshot. It stops short of saying when to pick click over press/longpress/gesture, so no exclusion vs alternatives.

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 no annotations, the description carries the full behavioral burden. It discloses mutability, the Android shell-command mechanism, the refusal behavior on unsupported builds, and the 90-second timeout. This is strong operational context, though it does not detail return/response behavior beyond what the output schema presumably covers.

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 compact sentences with no filler. The core purpose comes first, followed by the Android-specific caveat and the timeout constraint. 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?

Given an output schema, the description does not need to explain return values. It covers purpose, mutation, platform-specific failure behavior, and timeout. It is complete for practical invocation, though platform coverage beyond Android relies on the schema's platform selector.

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 89%, so the baseline is 3. The description adds only that 'given text' replaces clipboard contents, which lightly maps to the text parameter, but it does not enrich parameter meaning beyond the schema's existing descriptions.

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?

Clearly states the two operations ('read' / 'write') and the resource (device clipboard text) with a specific verb. It is unambiguous and distinguishable from the sibling list, where no other tool is clipboard-specific.

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 makes the tool's purpose obvious, but it does not explicitly say when to use this tool versus alternatives or when not to use it. The usage context is implied rather than stated.

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 no annotations, the description carries the full burden and does real work: it discloses the Android ADB failure mode (android-app-close-timeout when the app stays foreground or the process survives the 2s check window) and the 90s overall timeout. It does not state what state is lost when the app is killed or how the force flag changes failure behavior, which keeps it from a 5.

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 primary action and default, then the sibling routing, then the failure modes. Every sentence carries operational information; no restatement of the name or 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 20-parameter, zero-annotation tool the description is remarkably complete on the risky parts: scope, error conditions, and timeout budget. It stops short of describing what the response returns (no output schema exists) or how the mutation affects app data, but nothing needed to select and call it correctly 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 95%, so the baseline is 3, but the description adds genuine meaning beyond the schema's "Optional app to close" by defining the default resolution (active session app). The remaining 19 device/session/lease selectors are left entirely to the schema, which is reasonable given their coverage.

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 ("Close the named app") plus the default target when the argument is omitted, so the agent knows exactly what happens with zero args. It also explicitly separates itself from the sibling tool shutdown, so it is distinguishable without opening the 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 alternative (shutdown) and the condition that selects it: when the simulator/emulator itself should also stop. The omission case (no app arg) is also spelled out, leaving nothing to inference about which tool or argument to use.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the 90s timeout and matching UUID requirement, but it omits whether symbolication is read-only, whether an 'out' path creates or overwrites files, permission requirements, failure behavior, and response shape. That is thin for a 20-parameter tool with no 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: purpose first, sibling routing second, timeout third. It is front-loaded and every sentence earns its place, especially the alternatives list that prevents misuse.

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?

Purpose, sibling routing, and timeout are present, and the schema richly documents the 20 parameters. However, with no output schema and no annotations, the description should say more about return values, errors, and output-file behavior; as written it is adequate but incomplete for a complex tool.

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 95%, so the schema already documents artifact, dsym, searchPath, out, and selectors. The description only restates the matching-dSYM-UUID idea and adds no syntax, format, or selector guidance beyond what the schema provides, making the baseline 3 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?

Opens with the specific verb 'Symbolicate' and resource 'Apple crash artifacts', and scopes it to matching dSYM UUIDs. The namespace sentence names the sibling tools that handle adjacent evidence, so an agent can distinguish this tool from logs, network, perf, and others.

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 explicitly routes non-debug evidence to alternatives: logs for app logs, network for HTTP, perf for performance, record/trace for media and traces, and react-devtools for React Native. Combined with the first sentence, this gives both when-to-use and when-to-use-another-tool 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a 90-second timeout, which is a concrete operational detail. However, it does not state whether the operation is read-only, whether it requires special permissions, or how it behaves on failure or partial results. The timeout is useful but the overall behavioral picture is incomplete.

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 with zero waste. The purpose is stated first, followed by a practical usage hint and a timeout note. Every sentence earns its place, and the description is appropriately brief for a list tool.

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 tool has a rich output schema (true) and 15 optional parameters all documented in the schema, so the description need not explain return values. It covers the core purpose, the selector reuse pattern, and the timeout. For a discovery tool, this is sufficient; the only minor gap is that it doesn't explicitly mention that the filters are optional or that the output is a list, but these are implied by the verb 'List' and 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 each parameter is already documented in the input schema. The description mentions platform, device, udid, or serial as selectors, but this primarily guides usage of later commands, not the parameters of this tool itself. It adds little semantic meaning beyond what the schema provides, so the 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 the action 'List' and the resource 'available devices and simulators' explicitly, and clarifies the purpose 'can be selected for automation.' The verb is specific and distinguishes it from action-oriented siblings like boot, click, or install, which have clearly different purposes.

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 clear guidance on how to use the output: 'Use platform, device, udid, or serial inputs on later commands to target one result.' This explains the primary use case. However, it does not explicitly mention when not to use this tool or name alternative listing tools (e.g., get, find), though the siblings suggest those might serve other resources. The guidance is sufficient but not exhaustive.

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 no annotations the description carries the full behavioral burden. It usefully discloses a hard constraint ('Times out after 90s'), but says nothing about permissions, side effects, recording behavior (relevant given the noRecord param), or how the diff is returned. The timeout disclosure is genuine added value, but the rest of the behavior is left to the 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?

Three tightly written sentences, front-loaded with purpose before mode selection and the timeout caveat. No filler or restatement of the tool 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?

An output schema exists, so return values need not be described, and the timeout is covered. But for a 22-parameter tool with no annotations, the description omits any safety/side-effect profile and any guidance on the many resolution-related parameters, and the snapshot/screenshot mode discussion does not match the schema's single-valued kind.

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 73% across 22 parameters, and the description adds no parameter-level meaning for out, raw, depth, scope, interactiveOnly, or the device selectors. Worse, it implies a 'screenshot' comparison mode while the schema constrains kind to the single value 'snapshot', so the description is actively misleading about the parameter space.

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 ('Compare accessibility snapshots or screenshots') plus the goal ('identify UI changes'), which is clearly distinct from the sibling snapshot and screenshot tools that merely capture. It stops short of explicitly naming those siblings or how to pick between them, but the purpose 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?

It gives explicit mode-selection guidance ('Use snapshot comparisons for semantic tree changes and screenshot comparisons for pixel differences'), which is more than implied usage. However, no guidance is given for choosing diff over its siblings snapshot/screenshot, and the guidance is partly unusable because the schema pins kind to the const 'snapshot'.

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 no annotations provided, the description carries the full transparency burden. It discloses a notable background side effect (XCTest cache warming on iOS simulators), a 90-second timeout, and the output shape ('compact evidence'). This goes beyond a generic 'diagnose' and gives the agent actionable expectations, though it could go further on potential state changes beyond cache warming.

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 the purpose front-loaded, followed by return evidence and then the critical side-effect warning and timeout. Every sentence contributes new information, and nothing is redundant with the schema or output 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?

For a broad diagnostic tool with an output schema and fully documented optional parameters, the description provides everything needed to decide when and how to invoke it: what it checks, what it returns, the cache-warming side effect, and the 90s timeout. Even with 17 parameters, the schema fills the remaining detail, so the description is 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 structured schema already documents all 17 optional parameters. The tool description adds no parameter-specific semantics—it only discusses overall behavior and output—so the 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?

The description states a specific action ('Diagnose') and a concrete resource scope: device, app, development-server, and React Native or Expo readiness issues. It also enumerates the returned evidence (local inventory, sessions, app discovery, toolchains, server reachability), which clearly differentiates it from single-purpose sibling commands like screenshot or gesture.

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 tells the agent to run this before the first Apple snapshot or interaction of a session to warm the XCTest runner cache, which is a clear, concrete use-case. It stops short of naming alternatives or stating when not to use it, so it does not fully satisfy the 'explicit when/when-not/alternatives' level.

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 no annotations provided, the description carries the behavioral disclosure burden. It does reveal that the operation is read-only, returns paged JSON-friendly entries, and times out after 90 seconds. However, it does not explain pagination mechanics, the entry shape, or what happens on timeout, leaving some behavioral gaps.

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 very brief and front-loaded, with the core verb and resource stated first and the timeout note as the only extra detail. It is economical, though the missing punctuation and run-on feel ('entries Times out') make it slightly less polished than ideal.

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?

There is no output schema and no annotations, and the description does not explain the event entry structure, pagination behavior, required selectors, or response format beyond 'JSON-friendly entries.' For a tool with 17 parameters and several sibling tools, this is a significant contextual gap.

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 88%, so the schema already documents almost all parameters. The description adds little parameter-specific meaning beyond implying the relevance of paging through limit and cursor, and it does not clarify the two undocumented parameters (limit, cursor). The baseline of 3 is appropriate given the strong schema coverage.

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 ('Read'), a clear resource ('daemon-owned session event timeline'), and the output form ('paged JSON-friendly entries'). It is clear about what the tool does, though it does not explicitly differentiate it from similar sibling tools like logs, trace, or session.

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?

No guidance is given for when to use this tool versus alternatives. The sibling set includes related tools such as logs, trace, session, and replay, but the description provides no selection criteria, exclusions, or context that would help an agent choose correctly.

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 no annotations, the description carries the burden and does disclose useful traits: a 90s timeout with caller-supplied budget extension, the recordAs live-send-but-redact behavior, and the empty-string clear semantics. It stops short of stating failure modes, permission/auth requirements, or whether the mutation is reversible.

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 and five compact sentences with little waste. The middle sentence ('Inspect unconfirmed evidence and assert the expected value or resulting screen before continuing') is vague procedural advice that dilutes rather than sharpens the definition.

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 26-parameter mutation tool with no annotations, the description covers target modes, timeout, and one privacy behavior, but leaves permission needs, error/failure behavior, and the semantics of the many device/resolution parameters entirely to the schema. An output schema exists, so return values need no explanation.

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% across 26 parameters, so the schema already documents target, text, recordAs, timeoutMs, verify, etc. The description reinforces only a few (text clearing, ref/selector preference, recordAs) and adds no syntax or interaction detail beyond what the structured fields provide.

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 ('Replace text in a UI input') and enumerates the three targeting modes (ref, selector, coordinates). However, it never distinguishes itself from the sibling 'type' tool, which on its face performs a very similar text-entry operation — an agent choosing between them gets no signal.

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 implied guidance ('Prefer refs or selectors after snapshot', 'Pass an empty text to clear the field', use recordAs for sensitive text). That is real context, but there is no explicit when-to-use-this-vs-'type'/'click'/'press' routing, and no stated preconditions such as requiring a prior snapshot.

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?

No annotations, so the description carries the full burden. It usefully discloses a 90s timeout and the pre-reconciliation spelling behavior during a deprecation window, which are non-obvious traits. However, it says nothing about whether actions mutate state, permission/prerequisite needs, or how recording interacts with actions despite a record param existing.

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?

Core behavior is front-loaded in the first sentence, followed by a role/deprecation clarification and a timeout note. Every sentence contributes, though the middle clause is dense and could be tightened.

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 an output schema present, return values need not be explained, and the description covers locators, role vocabulary, and timeout. But for a 26-parameter tool spanning device/session/lease selectors, the description does little to orient an agent on the large selector surface, leaving much of the complexity to 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 coverage is 65%, with many selector params (device, serial, udid, session, lease, target) documented in the schema itself. The description adds meaning for the locator/role vocabulary and role matches against snapshot kinds, but does not clarify query vs value vs id semantics. Baseline 3 is appropriate given the partial schema coverage.

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 (find) plus the locator dimensions it searches and that it will run an action on the match. This distinguishes it from pure interaction siblings like click/fill, though it doesn't explicitly name which sibling to prefer for narrow cases such as get or snapshot.

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?

There is no explicit when-to-use guidance or comparison to sibling locators/commands (get, is, snapshot, click). The agent must infer that find is the general locate-and-act path, and the deprecation-window note adds detail but not usage routing.

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?

No annotations are provided, so the description carries the full burden. It discloses the 90-second timeout and the no-text-entry behavior, which is useful. However, it doesn't disclose potential failure modes, prerequisites (e.g., visible target), or what the response contains, leaving meaningful gaps for a UI-mutating operation with zero annotation coverage.

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 the core purpose front-loaded first. Every sentence earns its place: purpose, usage guidance, and timeout. No filler or redundant wording.

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 coordinate-based focus tool with no output schema, the description covers purpose, usage routing, and timeout. It could mention response shape or failure behavior, but the tool's simplicity and the fact that most of the 18 parameters are shared selectors (udid, device, platform) mean the description is reasonably complete for an agent to call 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?

Schema description coverage is 100%, so the baseline is 3. The description's 'explicit screen coordinates' maps to x/y, but that context is already implicit in the schema's 'X coordinate' and 'Y coordinate' entries. The description adds no parameter details beyond what the schema provides.

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: 'Move input focus to explicit screen coordinates without entering text.' This is clear and the 'without entering text' clause differentiates it from type/fill siblings. However, it doesn't explicitly distinguish focus from other coordinate-based siblings like click or hover, so it falls just short of a 5.

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?

'Prefer semantic interactions when a snapshot ref or selector is available; use type or fill after focus' gives explicit when-to-use guidance and names the complementary tools (type/fill). It doesn't enumerate exclusions relative to click/hover, but the coordination guidance is genuinely useful and clear.

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 no annotations, the description carries the full burden and delivers: platform-specific mechanics (iOS sends a HID hinge event then reads back the angle from CoreDevice; Android sets the emulator console posture, confirms the guest-committed state, reports the AVD-defined hinge angle, and dismisses the cover-display lock screen). It discloses failure semantics (UNSUPPORTED_OPERATION/unsupported-device-scope), staleness of refs/coordinates requiring a re-snapshot, environment requirements, and a 255s timeout.

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?

Purpose is front-loaded in the first sentence, but the body is a dense, multi-clause run-on covering device mechanics, lock-screen behavior, app relocation, staleness, and timeouts. Content is high-value but packed without paragraph or bullet structure, slightly hurting scanability.

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?

An output schema exists so return values needn't be explained, and the description compensates for the absence of annotations with thorough behavioral coverage including the critical re-snapshot-after-fold instruction. The main gap is that it never states which Android and iOS values/platform selector combinations are valid or what the keyframes-vs-pose exclusivity means at the schema oneOf level.

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 all 18 parameters are already documented in the schema, making the baseline 3. The description adds behavioral meaning for the pose/keyframe distinction (instant preset vs. timestamped angle keyframes, with the confirmation/readback behavior), but does not extend the many device-selection parameters.

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 (fold/unfold) and resource (foldable iPhone simulator / Android emulator) and enumerates the three poses it can reach. An agent can distinguish this from siblings like open, close, or orientation without opening any 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?

The description implies when to use it (foldable simulators/emulators, pose changes) and discloses a hard precondition: a simulator scoped to a non-default simulator set is refused with UNSUPPORTED_OPERATION, and the tool is simulator/emulator-only. However it names no explicit alternative for non-foldable devices, so it falls short of a true when/when-not mapping.

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 no annotations, the description carries the full disclosure burden, and it does contribute two genuinely useful behavioral facts: a hard 90s timeout and the constraint that a tap spans 2–5 simultaneous contacts. It says nothing about whether the action is recorded (despite a noRecord parameter), what happens on failure, or whether a device lease/session must already exist — significant omissions for a 35-parameter interaction tool.

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, front-loaded with the verb and the kind enumeration. Every sentence adds a distinct fact — kind selection, tap semantics, and the timeout — with no filler or restatement of 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?

No output schema exists, so the description is not obliged to explain return values, and the tap and timeout notes cover the trickiest bits. However, for a tool with 35 parameters spanning device selectors, sessions, leases, and response-format flags, the description says nothing about device targeting, prerequisite state, or response behavior, leaving real gaps.

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 would be 3, but the description adds value the schema cannot: it establishes that parameters are conditional on kind rather than a flat bag of 35 inputs, and it explains the tap-specific pairing of points with count and pauseMs. It could have gone further by mapping other param groups (preset/direction/distance, scale/degrees) to their kinds, which the schema only partly does.

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 enumerates all eight gesture kinds, so the resource and its scope are unmistakable. It never distinguishes itself from sibling tools like swipe, longpress, or scroll that overlap with at least three of those kinds, leaving an agent to guess which one to pick.

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?

"Select the gesture kind, then provide only the inputs that apply to that kind" gives real intra-tool guidance on how to drive the schema, and the tap sentence clarifies repetition semantics. But there is no when-to-use framing against the obvious alternatives (swipe, longpress, scroll, click) and no mention of prerequisites such as an active session or lease, so usage is only implied.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation is non-mutating ('without changing the app') and adds a specific timeout ('Times out after 90s'), which goes beyond the schema. It does not cover every error or edge case, but the key safety and timing traits are present.

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 sentences with no filler. The primary purpose and read-only nature are front-loaded, followed by format usage and the timeout. Every sentence earns its place and the structure is optimal for quick agent scanning.

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 21 parameters and no output schema, the description covers the essential invocation semantics: what to read, how to specify the format, that the operation is safe, and the timeout. Many optional parameters are left to the schema, but the core context an agent needs to select and call this tool correctly 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 95%, so the baseline is 3. The description adds meaningful semantics for the core parameters: it explains what 'format' values produce ('text for visible content', 'attrs for the element attribute map') and clarifies the target as 'snapshot ref or selector'. This is valuable beyond the bare schema enumerations.

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 ('Read') and resource ('text or accessibility attributes') from a 'snapshot ref or selector', and explicitly notes it does so 'without changing the app'. This makes it clearly distinguishable from siblings like snapshot or find, and the purpose is immediately apparent.

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 clear context for when to use the tool: when you need visible content or an element attribute map from a ref or selector. It also gives format-selection guidance ('Use format text for visible content or attrs for the element attribute map'), though it does not explicitly contrast with alternative sibling 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it explains that the press is dispatched without activating the session app, nothing is re-observed, the OS decides routing, power toggles the screen, sleep/wake are explicit events, screen-off may cause later commands to hit a locked screen, and the command times out after 90s.

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 front-loaded with the core action and button list, then layers on constraints and side effects. It is dense and a bit long, but most sentences carry relevant operational detail for a complex hardware-control tool.

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 no annotations, a rich input schema, and an output schema, the description is complete enough to call the tool correctly. It covers platform support, refusal cases, side effects, timeout behavior, and the command's non-observational nature.

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 useful meaning around the button parameter by explaining OS routing, Android versus Apple support, and device-behavior limits. It does not add much for the many selector/session parameters beyond what the schema already documents.

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: 'Press a phone hardware button once,' then enumerates the supported buttons. It also distinguishes itself from television controls by directing TV targets to tv-remote, so an agent can identify its scope without opening the 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?

It gives explicit platform conditions: Android supports all eleven buttons, physical Apple devices support only volume, iOS Simulators and TV targets refuse, and TV users should use tv-remote. This provides clear when-to-use and when-not-to-use guidance plus an alternative.

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?

No annotations are present, but the description discloses the two response modes (card vs. guide) and states that a tool name yields its complete flag reference, which is meaningful behavioral detail beyond the schema. It also proactively suppresses unnecessary calls, reducing wasted round trips. It does not say the output is plain text vs. structured or whether the guide is long, so it stops short of 5.

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 primary behavior and the default (no topic), then the value space, then the guardrails. The long topic enumeration is necessary but makes the middle a comma wall that is slower to scan than a list. Every sentence still carries information, so it is efficient, just dense.

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 one-parameter, no-side-effect lookup with no output schema, the description covers trigger conditions, default behavior, and the full value space. The only gap is what the returned guide/card actually looks like and how large it is, which matters if an agent is weighing whether to call it mid-task.

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% but defines no enum, leaving 'topic' effectively unbounded. The description supplies the actual accepted space — ~20 named topics plus the rule that any tool name is valid for flag reference — which the schema cannot convey. This is exactly the kind of additive semantic guidance the description should carry.

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 ('Usage guides') and explains the two operating modes: no topic returns a root decision card, a topic returns that guide. 'Root decision card' is slightly internal jargon, but combined with the topic list an agent can tell exactly what this tool returns, distinct from every sibling.

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 scopes use to 'specialized work or an unclear command shape only' and names two exclusions: not a startup step, and not needed after an error that already carries a hint. That is a precise when/when-not with an implied alternative (rely on the hint instead).

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 no annotations, the description carries the full burden. It discloses that the app session remains open and that the tool times out after 90 seconds, which are key behaviors. It does not detail side effects like whether the home button is pressed or what happens on timeout, but the provided details are useful.

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 concise sentences, with the core action front-loaded and the critical behavioral nuance in the second sentence. No redundant information.

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 tool is simple in purpose and the output schema is present, so the description covers the essential facts (action, session behavior, timeout). It does not mention platform-specific behavior (mobile/tv/desktop) despite the target parameters, but the schema and output schema fill most gaps. Adequate for a straightforward navigation tool.

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 no additional meaning to any of the 16 parameters; all semantics are already captured 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 states a specific verb and resource: 'Send the selected device to its home screen.' It clearly distinguishes the action from navigation tools like 'back' by explicitly noting it leaves the app session open, which is a defining behavioral difference.

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 some implied usage context (e.g., it moves foreground away from the app) but does not explicitly state when to use this tool versus alternatives like 'back' or 'app-switcher'. No exclusions or alternatives are named.

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 no annotations, the description carries the burden and discloses key traits: it does not press (pure read-side hover), it is web-only, it has a 90s timeout, and a caller-supplied budget can extend it. It omits whether the action is recorded or what happens on non-hover-gated targets, but the timeout and platform constraints are substantive.

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 compact sentences, each carrying distinct information (action, target modes, platform constraint, settle tip, timeout). The core action and target modes are front-loaded before qualifications.

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?

Output schema exists, so return-value explanation is unnecessary. Given 22 parameters, the description sensibly does not attempt to cover them all and focuses on the ones that matter (target, settle, timeout). Minor gap: no mention of device/session selection context or recording behavior, but nothing an agent needs to call it correctly 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 baseline is 3, but the description adds meaning the schema does not: it frames the three target kinds as interchangeable recognition modes and explains that settle lets you capture what hover revealed without a follow-up snapshot, which clarifies that parameter's purpose. Timeout/budget semantics are also explained.

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 ('Move the pointer over') and resource, enumerates the three targeting modes (snapshot ref, selector, coordinates), and gives the intent ('reveal hover-gated UI such as row toolbars or menus'). It is clearly distinguishable from siblings like click, press, and longpress.

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 scopes the tool to 'Web only' and explains why: 'touch platforms have no hover state', which is a genuine when-not-to-use rule. It also advises using settle to observe the revealed UI. It stops short of naming alternative tools for non-hover scenarios, so it is strong but not fully routed.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses a 180s timeout, which is a behavioral detail. However, it does not state whether the install overwrites an existing app, what happens on failure, or any required permissions. The mutation nature is implicit, but there's limited additional transparency beyond the timeout.

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 sentences with no wasted words. It front-loads the purpose, then provides usage guidance and a timeout note. Every sentence earns its place, making it concise and well-structured.

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 absence of an output schema and the full schema coverage of parameters, the description covers the core operation, directs to reinstall for replacement, and notes the timeout. It does not specify behavior when the app is already installed, but that is handled by the reinstall reference. The description is sufficiently complete for an install command, though it could mention failure handling or overwrite 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 description adds meaning to two parameters: it clarifies that 'app' is an identifier (via 'Provide an app identifier') and that 'appPath' is a local path (via 'from a local path'). This provides additional context beyond the schema, though it doesn't elaborate on the other 16 parameters. Given the high schema coverage, the description compensates adequately.

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 purpose: 'Install an app binary from a local path.' It uses a specific verb ('Install'), resource ('app binary'), and source ('local path'). It differentiates from the sibling 'reinstall' by explicitly stating 'use reinstall to replace an already installed app,' which helps an agent distinguish between the two.

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 usage guidance: it tells the agent to provide an app identifier when explicit app selection is needed, and directs to 'reinstall' when replacing an already installed app. This clearly indicates when to use this tool versus the alternative. It also mentions the 180s timeout, which is useful context.

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 a 90-second timeout and remote daemon resolution, which are useful behavioral details. However, with no annotations, it omits prerequisites, side effects on the device, reversibility, or failure behavior. For a mutation tool, this is partial disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.