polyscreen-mcp

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

Adds substantive context beyond the annotations: the output is heuristic buckets that may need calibration, the timeline is omitted by default, and mode='flash' expands into a preset. Annotations mark readOnlyHint=false, and the mention of exportSampleFrames is consistent with producing artifacts, though the description never explicitly states that files are written.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense, front-loaded sentences with no filler; the core action leads and the calibration and defaults follow. The first sentence is long, but each clause carries distinct, 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?

For an analysis tool with an output schema, the description covers the sampling method, bucketing semantics, calibration caveat, and key mode/timeline defaults. It omits the fact that readOnlyHint=false implies artifact writes, which is a minor gap given the structured fields already 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 coverage is low (27%) across 11 params, so the description must compensate. It clarifies mode='flash', includeFullTimeline, exportSampleFrames, and implicitly blackThreshold (16=true_black), but leaves fps, path, marks, serial, artifactUri, dimThreshold, and timelineDownsampleMs unexplained. Partial but incomplete compensation warrants the baseline 3.

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 specific verbs (sample, detect, classify) and resource (MP4 recording via ffmpeg), and enumerates the exact brightness buckets it produces. An agent can distinguish this analysis tool from capture/record siblings like mobile_screen_record or mobile_theme_flash_report 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?

Gives clear context and a named alternative: calibrate heuristics with exportSampleFrames on the device under test, and use mode='flash' for one-call regressions. It stops short of explicit when-not-to-use guidance, but the routing signal is strong.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety burden is covered. The description still adds genuine resolution semantics beyond the annotations: window focus is preferred and activity top is the fallback, telling the agent how the returned value is derived.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the primary purpose front-loaded and the fallback behavior following. Every clause earns its place; no restatement of the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description need not explain return shape. It covers purpose, scope and resolution precedence; the only minor gap is unspecified behavior when no window holds focus or when several displays exist.

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 both parameters are already documented (including the ADB serial caveat and the logical-display distinction). The description's 'one logical display' phrasing only echoes displayId without adding syntax or format detail, so the baseline 3 applies.

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 ('Return') and resource ('focused package and activity') plus a scope qualifier ('for one logical display'). An agent can tell this reports foreground state, but the description never names a sibling (e.g. mobile_app_inspect, mobile_focus_trace) to differentiate against.

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 use case is implied clearly enough by the description, but there is no explicit when-to-use, when-not, or alternative named among the many app/focus siblings. An agent must infer the routing on its own.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description. The description's enumeration of what it reads adds some scope context, but an output schema exists that would reveal the returned fields, so the marginal disclosure is modest. No auth requirements, device-precondition, or cost details are added.

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?

A single front-loaded sentence with no filler; the verb and resource lead and the enumeration follows. Every clause carries information and nothing is 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 low-complexity read-only tool with an output schema (so return values need not be explained) and complete safety annotations, the description covers purpose and content adequately. Its main residual gap is the absence of routing guidance among the large set of mobile_app_* siblings and the undocumented packageName parameter.

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 50%: serial carries a strong schema description (pointing to mobile_devices_list and the multi-device inference rule), but packageName documents only a regex pattern with no explanation. The description itself says nothing about either parameter, so it fails to compensate for the documented half-gap. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (read) and resource (package), and enumerates scope: state, permissions, components, users, installation metadata. This clearly separates it from the many sibling action tools. It does not explicitly contrast with the close sibling mobile_device_inspect, but the 'package' framing implies app-level vs device-level, so it stops just short of the 5 bar.

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 when-to-use or when-not-to-use guidance, and no named alternatives. The description never tells the agent to prefer this over mobile_device_inspect or when inspecting an app is the right step. Usage must be inferred entirely from the name and title.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, openWorld=true, so the safety profile is covered. The description usefully adds that the operation is timeout-bounded and returns a structured ADB result, but says nothing about failure behavior, whether a live device session is required, or what 'replace' does to existing installs.

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?

A single front-loaded sentence with no filler; the core action and its constraints come first. It is arguably under-specified rather than over-long, but the structure itself is efficient.

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, explaining the return value is unnecessary, and the bounded-timeout note is useful. However, for a 3-parameter mutation tool at 33% schema coverage it leaves the 'replace' semantics and the local-device prerequisite unaddressed, so it is only minimally sufficient.

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 only 33%, so the description must compensate and largely does not. It clarifies that 'path' is a local APK, but adds nothing about 'replace' (default true) or about the timeout it mentions having no corresponding parameter. 'serial' is documented in the schema, not the description.

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 ('Install one local APK') and adds scope constraints ('local', 'one', 'bounded timeout', 'structured ADB result') that separate it from mobile_app_launch, mobile_app_uninstall, and mobile_app_inspect. It stops short of naming a sibling condition explicitly, so the differentiation is inferable rather than stated.

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: nothing says to install only when the app is absent, nor routes the agent to mobile_app_launch for already-installed apps or mobile_app_uninstall for removal. The only implicit signal is 'local APK', which hints at a prerequisite but not a decision rule.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive behavior. The description adds value with 'resolve' (implies failure if the activity/package cannot be resolved) and 'ActivityManager wait diagnostics' (implies it waits and reports diagnostics), which go beyond the annotations. It still omits what happens on a cold start, whether an existing instance is foregrounded, and any error surface.

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?

A single dense sentence with no filler, and the core action is front-loaded. It is efficient, though the trailing 'ActivityManager wait diagnostics' clause is jargon that a reader must decode.

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 annotations cover the safety profile. What remains missing is routing guidance against lifecycle siblings and clarification of the packageName/activity/userId semantics, leaving the definition adequate but not self-sufficient.

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 only 40%, so the description should compensate, but it mainly echoes the displayId schema text ('logical display') and only vaguely gestures at 'activity'. It explains nothing about the tricky userId parameter or the interaction between packageName and the optional activity argument.

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 (resolve and launch) and resource (an activity on a logical display) plus a behavioral detail (ActivityManager wait diagnostics). However, it gives no differentiation from close siblings like mobile_app_relaunch_on_displays, mobile_app_foreground, or mobile_app_stop, so an agent cannot route confidently between them from the description alone.

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 statement of when to use this tool versus alternatives, despite the crowding of app-lifecycle siblings (relaunch_on_displays, foreground, stop). No prerequisites, no conditions, no exclusions are given.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds real behavioral detail beyond them: the stop-then-launch ordering, per-display iteration "in order", and that it is a forced (not graceful) stop. It omits any permission/auth notes or what state is lost on the force-stop.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the action and sequencing front-loaded; every clause earns its place and no filler is present.

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 annotations carry the safety profile. The main gap is the low schema coverage on userId and settleMs, which the description does not compensate for.

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 only 17%, so the description carries weight here. It touches packageName, activity ("main (or given) activity") and displayIds scope, but adds no meaning for serial, userId, or settleMs, whose defaults and constraints live only 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?

States a specific compound action (force-stop then launch) applied to a named resource (package/activity) across a scoped target (each logical display). It clearly distinguishes itself from siblings mobile_app_launch and mobile_app_stop by the ordered multi-display sequence.

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 for dual-display cold-start / flash reproduction" gives explicit context for selecting this tool over plain launch/stop. It does not state when not to use it or name an alternative for single-display cold starts, so it falls short of the top band.

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

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

Annotations declare the safety profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false), and the description adds real value beyond them by naming what actually gets terminated: the package's processes and pending implicit launches. It still omits permission requirements and whether the app is removed from recents, but it meaningfully extends the annotation-covered profile.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the action first and the scope qualifier second. No filler, no 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 values need not be described, and annotations cover safety, but with an undocumented userId and packageName the definition leaves gaps an agent must resolve. Adequate but incomplete for a 3-param mutation 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 only 33% (serial documented; userId and packageName bare except for a pattern/default), so the description carries the burden to compensate but adds no parameter meaning at all. Neither how userId='current' behaves nor the packageName format is explained in prose.

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?

Specific verb 'force-stop' plus resource 'package', with added scope ('processes and pending implicit launches') that clarifies what stopping entails. It does not explicitly differentiate from near siblings like mobile_app_uninstall or mobile_app_relaunch_on_displays, but the action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to use this versus alternatives (e.g., uninstall, relaunch, or launch/reset flows), no prerequisites, and no note that the app must be installed/running. The agent must infer all usage context from the name alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The phrase 'optionally retaining its data' adds genuine context about data destruction, but the description never states what the default (keepData=false) does or that the removal is irreversible.

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?

One short sentence with the action front-loaded and no filler. It is efficient, though its brevity is partly the cause of the other gaps rather than a virtue.

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 annotations carry the destructiveness profile. Still, for a destructive, non-idempotent tool the description omits when to use it and provides thin coverage of the two undocumented parameters.

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 only 33%: only 'serial' carries a description; 'packageName' (pattern only) and 'keepData' (boolean, default false) are undocumented. The description gestures at 'keepData' via 'retaining its data' but adds no format or default semantics beyond the schema's bare type.

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 ('Uninstall') and resource ('a package'), which cleanly separates it from the install/launch siblings. It does not, however, distinguish itself from other mutating app tools like mobile_app_stop, leaving the agent to infer the 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 no when-to-use guidance, no prerequisites, and no indication of when to prefer mobile_app_stop or a reinstall instead. Only the existence of the tool itself is conveyed.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real value beyond them by specifying the shape of the returned metadata (uri, name, mime, size) and explicitly ruling out binary payload retrieval.

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, purpose and return shape front-loaded, negative scope immediately after. Nothing is wasted or repeated from 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?

An output schema exists, so return-value documentation is not strictly required, yet the description still names the stub fields. For a read-only one-optional-param list, only pagination/limit semantics and the artifact-root location are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single 'limit' parameter has 0% schema description coverage and the description never mentions it — no statement of whether it caps total results, whether listing is paginated, or what the 200 default implies. With a non-zero uncovered parameter, the description fails to compensate.

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?

Specific verb+resource ('List metadata stubs ... for files under the artifact root') with the exact returned fields enumerated. It is readily distinguishable from the only nearby sibling, mobile_artifacts_prune, by the verb, but the sibling is never named, so it falls short of the 5 bar.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'Does not embed binary contents' signals this is the cheap enumeration path, but there is no explicit when-to-use, no prerequisite, and no mention of alternatives such as prune or the analyze tools.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the destructive nature is covered. The description adds that dryRun previews (useful), but omits whether deletion is permanent, whether combined criteria are AND or OR, and what maxCount=0 or maxAgeMs=0 means.

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, front-loaded with the core action and criteria, with the dryRun preview tip second. 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 values need no explanation, and annotations carry the safety profile. For a zero-required-parameter destructive tool this is nearly complete, missing only the AND/OR combination semantics of the retention criteria.

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 0%, so the description must carry the load, and it does name all three parameters' roles: maxAgeMs for 'old', maxCount for 'excess', and dryRun for 'preview'. It stops short of stating units or default behavior, so it is good but not complete.

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 (delete) plus resource (artifact files) and the controlling criteria (maxAgeMs and/or maxCount), which clearly separates it from the read-only sibling mobile_artifacts_list. It does not explicitly name the sibling, but the action and scope 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?

"Use dryRun to preview" gives one actionable usage hint, implying the tool should be previewed before committing. However, there is no guidance on when to prune vs. simply listing artifacts, no prerequisites, and no note on how the two criteria combine.

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

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

Adds real behavior beyond the annotations: each step is schema-validated, nested batches and certain tool types are rejected, and stopOnError terminates the sequence on first failure. These are meaningful execution semantics. It stops short of noting the 16-step cap or ordering/rollback behavior on partial failure.

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 tight sentences, front-loaded with the core action, then validation, then exclusions, then the stopOnError flag. No filler; each clause carries a constraint or behavior.

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 covering returns and annotations covering the safety profile, the description supplies the operational constraints an agent needs (validation, rejected step types, stopOnError). Missing the 16-step limit and the mobile_-prefix requirement keeps it from being fully 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 0%, so the description must carry the load. It explains stopOnError ('ends the sequence at the first failure') and that step args are validated, which adds value, but omits the minItems/maxItems bounds (1-16) and the mobile_ naming pattern, both of which the schema encodes only structurally.

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 clear verb and resource: 'Call other registered tools in one request' within an ordered sequence. The meta/aggregator role is unmistakable and distinct from the concrete UI/input siblings, though no sibling batch tool is named to contrast against.

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?

Implies that this is the tool for chaining multiple operations, and it explicitly lists what cannot be batched (nested mobile_batch, screenshots, blocking screen records). But it never says when batching is preferable to calling tools individually, nor what the alternative is.

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?

Despite annotations covering the safety profile, the description adds substantial behavioral context beyond them: the dumpsys-then-cmd fallback chain, the companion-session path when shell access is blocked, the denial behavior that names the companion, and the critical distinction between an empty string (verified empty) and readable=false (unseen clip). These details materially change how an agent interprets results.

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?

Six tight sentences, each carrying distinct behavioral information with no padding, and the primary read path is front-loaded. The telegraphic fragments ('set uses cmd clipboard set') trade readability for density but do not waste space.

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 an output schema and full annotations, the description covers the non-obvious edge cases an agent needs (fallback, denial, empty-vs-unreadable). It omits what a successful set returns and any permission prerequisites, but these are largely covered by the output schema and annotations.

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 only 33% (serial is documented in-schema), so the description must compensate and only partly does: it clarifies the semantics of get and set actions implicitly but never addresses the text parameter's 8000-character limit or writing behavior. Baseline for low coverage with partial compensation.

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 title and opening sentences make the resource (Android clipboard) and both directions (get/set) unambiguous, and no sibling tool competes for clipboard access. However, the description leads with implementation mechanics ('Read dumpsys clipboard, then cmd clipboard get') rather than stating the purpose directly, so an agent must infer intent from the mechanism.

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 get-vs-set distinction is only implied through the flow descriptions ('set uses cmd clipboard set'), and the default action=get is left to the schema. There is no explicit statement of when to prefer this tool or when clipboard access is inappropriate, so usage must be inferred.

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

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

Annotations already declare it is not read-only, not idempotent, and non-destructive, so the safety profile is covered. The description adds a genuine behavioral fact ('Non-foldables return foldable false') about edge-case output. It does not disclose auth needs, reversibility of a state change, or rate limits, so it is useful but not rich.

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 read behavior before the write behavior, with little waste. The wording is slightly tangled but the structure is efficient.

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 annotations carry the safety profile. It also notes the non-foldable case. What is missing is clearer usage framing and any statement about what a state change affects, which for a mutation-capable tool leaves a modest 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?

Coverage is 50%: 'serial' is documented in the schema (exact ADB serial from mobile_devices_list), and the description compensates for the undocumented 'state' param by giving valid value forms ('OPEN or CLOSED or a numeric identifier'). That is meaningful semantics beyond the bare schema for the undocumented parameter.

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 conveys that this reads fold postures and can set them, and the title reinforces 'Read or set fold state'. However the phrase 'List cmd device_state postures' is awkward and half-restates an underlying command rather than cleanly stating the resource, so the purpose is only adequately clear. It does not explicitly distinguish itself from siblings like mobile_orientation, but fold state is distinctive enough.

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 implies usage: call without state to list postures, pass state to switch. That conditional is useful but unstated in when/when-not terms, and no alternative tool is named for adjacent needs. Adequate minimum-viable 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds only the notion that it probes *actual* (live-observed rather than declared) capabilities, but says nothing about cost, latency, or whether probing has side effects on the device.

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?

One front-loaded sentence with no filler, though the trailing capability list reads as keywords rather than explanatory prose. It is efficiently sized for a simple two-parameter 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?

An output schema exists, so return values need not be explained, and the probes cover a low-complexity read. Still, the description leaves the refresh flag's effect and the intended workflow position (when to re-probe) unspecified, which leaves a gap for a two-parameter 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 coverage is 50%: serial is well documented in the schema, but 'refresh' (default false) is undocumented in both the schema and the description. The description never mentions the refresh parameter or what cache/probe semantics it toggles, despite 'actual' hinting that a cached-vs-live distinction exists.

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?

Specific verb ('Probe') plus a well-scoped resource (device ADB/input/command/build/backend capabilities), which separates it from mobile_app_inspect's app-level scope. It does not, however, explicitly distinguish itself from mobile_server_info or mobile_devices_list, which an agent might reasonably confuse it with.

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: nothing says whether this should be run before input/app operations, how often, or why the caller would pick this over mobile_devices_list or mobile_server_info. 'Probe the selected device's actual... capabilities' implies a diagnostic posture but leaves the trigger condition to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses that the same physical device may surface under multiple serials and that results are grouped by hardware serial with a preferred TCP serial and alias resolution. That is meaningful operational nuance.

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?

A single front-loaded sentence with no filler, and it packs the returned semantics in without redundancy. Nothing could be cut without losing 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?

With an output schema present, the description need not enumerate return fields, and annotations carry the safety profile, so the essentials are covered. The only real gap is the absence of explicit routing guidance relative to mobile_device_inspect and the other device-scoped siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The schema is an empty object and the description correctly does not invent inputs.

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?

Names a specific verb and resource ('List ADB devices') and goes further by describing what the listing contains (reachability, serial grouping, preferred TCP serial, aliases). This clearly separates it from single-target siblings like mobile_device_inspect, though that differentiation is implied rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the discovery/enumeration entry point before inspecting or acting on a device. There is no explicit when-to-use statement, no mention of prerequisites (e.g. ADB server running), and no named alternative for narrower queries.

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

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

Annotations already establish the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not obligated to restate it. It adds modest scope context by saying results include correlated capture IDs, evidence, and focus state, but does not describe ordering, paging, or failure 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?

A single front-loaded sentence with no wasted filler. It is appropriately terse, though the trailing 'with evidence and focus state' phrase is the least informative part and could be sharper.

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 detail is not the description's job, and the only parameter is fully specified. What is missing is usage context relative to siblings, not structural coverage.

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%, and the single serial parameter is already well documented in the schema, including the 'never inferred when multiple devices exist' caveat. The description adds nothing beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (list) and resource (logical displays) and adds that physical capture IDs plus evidence and focus state are correlated. It is clear on its own but never distinguishes itself from display-adjacent siblings like mobile_screen_capture or mobile_app_relaunch_on_displays, and 'evidence' is undefined jargon.

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, no prerequisite (e.g. needing a connected device first), and no mention of alternatives despite many displays/capture siblings. The intended invocation context is only implied by the name.

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

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

Annotations are weak here (readOnlyHint=false, idempotentHint=false, destructiveHint=false) and say nothing about the blocking nature or where output lands, so the description carries real value: it discloses that the call blocks and that large sample sets go to an artifact with only a compact prefix inlined. Missing dependency/permission requirements (e.g. root) and timeout risk, keeping it below 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?

Three tight sentences: purpose first, routing second, output behavior last. No filler, and the most decision-relevant 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?

An output schema exists, so return values need no explanation, and the description covers the blocking contract and artifact behavior. It stops short of covering prerequisites (root/permissions) and failure modes, which matters for a blocking call that can run up to 180s.

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 only 17% — serial and the displayIds item type are documented, but durationMs, maxSamples, sampleIntervalMs, and includeAllSamples have no schema descriptions. The description hints at duration and sampling volume (large sets to artifact, compact prefix inlined) but does not explain interval, cap, or includeAllSamples semantics, so it only partially compensates.

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 (blocking sample), resource (focused package/activity/taskId), and scope (fixed duration), and explicitly distinguishes itself from the mobile_focus_trace_start/stop siblings. An agent can select it 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 (mobile_focus_trace_start/stop) and the condition that selects it (interleaving input or recording), which is solid routing guidance. It doesn't spell out when-not beyond that single case, but the key decision point is covered.

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

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

Annotations already declare the safety profile (readOnly=false, idempotent=false, destructive=false), so the bar is lower, yet the description still adds real behavior: sampling is non-blocking, samples are ring-buffered up to maxSamples (i.e. old samples are overwritten), and recordOffsetMs alignment is produced when bound. It does not mention the lifecycle requirement to stop the trace or resource cost.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, front-loaded with the core action, then optional binding, then defaults and buffer behavior. No filler; every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no exposition, and the description covers action, key parameters, and buffering. The notable gap is lifecycle context: it never states the trace must be terminated with mobile_focus_trace_stop or whether concurrent traces are permitted.

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?

With schema coverage at only 20%, the description carries much of the burden and delivers: it explains boundRecordId's purpose, the default sampleIntervalMs (250ms), and maxSamples as the ring-buffer bound. It leaves serial and displayIds semantics to the schema, which happens to document them well.

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 ('Start non-blocking focus sampling for logical displays') and the 'async/non-blocking' framing distinguishes it from the synchronous sibling mobile_focus_trace. It does not name the sibling or mobile_focus_trace_stop explicitly, so differentiation is implied rather than stated.

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 binding-to-recordId note implies a key use case (aligning samples with record marks during a recording), which gives implicit context for when to reach for this tool. However, it never says when to use this versus mobile_focus_trace or the record_* family, nor any prerequisite or exclusion.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a state-mutating but non-destructive stop. The description adds real context beyond that: large traces write samples JSON to an artifact, a side effect not visible in the annotations. It does not explain reversibility or the artifact's lifecycle.

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 the main action front-loaded, and no wasted phrasing. The field-name parenthetical is slightly dense but earns its place by clarifying the return shape.

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 and annotations already present, the description need not re-explain returns, yet it still summarizes them and adds the artifact-writing behavior. The main gap is the undocumented includeAllSamples input, which is minor for an otherwise complete stop-and-collect 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 coverage is only 33% (only serial is documented). The description explains none of the input parameters and never mentions includeAllSamples, which is the one parameter most in need of clarification and is only given a default. The parenthetical field list (wallClockIso, tMs, recordOffsetMs) describes outputs, not inputs, so it does not compensate.

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 ('Stop an async focus session') and describes the return content (focus change events plus samples). It is clearly the stop counterpart to mobile_focus_trace_start, though it never explicitly names that 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?

'Prefer `changes` for flash/launcher hunting' gives steering on which output to consume, and stopping a started session is implied. But there is no explicit when-to-use vs alternatives (e.g., mobile_focus_trace vs mobile_focus_trace_start) and no preconditions 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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent, closed-world). The description adds that both taps occur 'in one on-device script', which hints at atomicity and reduced round-trips, but says nothing about target-side effects, failure modes, or confirmation 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 tight sentences with the core behavior front-loaded and the gapMs definition immediately after. No filler, though 'Pass ref or x and y' is a bare fragment that could carry precedence detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the serial/displayId/ref semantics live in the schema. The description covers the main ambiguity (gapMs, ref-or-coordinates) but leaves x/y semantics to inference, which is a minor gap for this complexity.

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 only 50% and x, y, and gapMs have no schema descriptions. The description partially compensates by defining gapMs as 'the pause between the taps' and framing ref vs x/y as alternatives, but x/y coordinate space and units remain undocumented.

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 ('inject two display-targeted taps at the same point') and clarifies the defining trait vs a single tap. It does not name mobile_input_tap as the sibling it supersedes, so discrimination relies on the agent inferring it from 'two taps'.

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: nothing says to prefer this over calling mobile_input_tap twice, or when gapMs matters relative to mobile_input_long_press. 'Pass ref or x and y' is argument instruction, not usage 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine value with 'capability-gated' (the call can fail when the device/display doesn't support the gesture) and the ref-precedence rule, but it never states that repeated drags mutate UI state non-idempotently or whether coordinates are display-relative.

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, no filler, with the core action front-loaded and the ref-precedence caveat second. Every clause carries information the schema doesn't.

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 ref-override rule closes the biggest gap. Still missing for a mutating gesture tool: what durationMs controls (only its 300ms default is visible) and what happens when the capability gate fails.

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 57%, and the description compensates by resolving a real ambiguity the schema leaves open: startRef/endRef override start/end when both are supplied. That precedence rule is the single most important thing to know about this 7-parameter schema. It still leaves durationMs's effect unmentioned.

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 action ('Inject a ... long-press drag-and-drop') on a specific resource ('one logical display'), which separates it from siblings like mobile_input_swipe and mobile_input_long_press. It never explicitly names those siblings, so the differentiation is inferential rather than stated.

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: nothing says to prefer this over mobile_input_swipe for a drag, or how it differs from mobile_input_long_press. The only conditional content is the ref-vs-coordinate precedence rule, which is parameter semantics rather than 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?

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=false, so the safety profile is carried by structured data. The description adds one real behavioral trait, that press options are 'capability-gated' (they may be unavailable depending on device capability), but it is too vague to be actionable and says nothing about how keys are resolved or what failure looks like.

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?

A single front-loaded sentence with no padding or repetition. It is efficient, though the vague 'capability-gated' clause consumes words without delivering usable detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, non-idempotent input tool with low schema coverage, the description leaves key syntax, action semantics, and duration behavior undocumented. An output schema exists so return values need not be covered, but the invocation-relevant gaps remain substantial.

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 only 33% (only serial and displayId are documented), so the description must compensate for key, action, source, and durationMs. It touches them only obliquely ('symbolic or numeric' hints at key format, 'gamepad source' echoes the source default, 'press options' hints at action) without explaining the accepted key syntax, the meaning of durationMs, or the non-idempotent semantics.

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 gives a specific verb and resource ('Send symbolic or numeric Android keys'), so an agent knows this injects key events rather than taps, swipes, or text. However, it never names the sibling it differs from (mobile_input_text, mobile_input_key_combination, mobile_input_key_sequence), so sibling differentiation is only implied by the 'key' noun.

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 mention of when to prefer this over mobile_input_text or the combination/sequence variants. The phrase 'capability-gated press options' gestures at a precondition but does not state one.

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

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

Annotations already declare this as a non-destructive but non-idempotent write operation, so the safety profile is covered. The description adds useful behavior: keys must be device-supported, ordering is significant, and durationMs governs the chord hold, but it omits auth requirements, device/session preconditions, and rate limits.

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?

One front-loaded sentence with no filler; the essential verb and resource lead the sentence. It is clean but extremely terse for a 5-parameter tool, leaving no room for structural grouping of constraints.

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 annotations cover safety. However, for a required 3-parameter input tool with only 40% schema coverage, the description omits key string format, source semantics, multi-device serial rules, and when to prefer this over sibling input tools, leaving meaningful 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 description coverage is 40%, so the description must compensate. It adds meaning for the keys array ('explicit ordering') and durationMs ('chord duration'), but gives no explanation of the source enum values or the key-string format expected in the array.

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 (inject) and resource (key combination) plus scope modifiers (ordering, chord duration). The word 'combination' conceptually separates it from mobile_input_key (single) and mobile_input_key_sequence (sequential), though no sibling is named 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, no conditions for choosing this tool over mobile_input_key, mobile_input_key_sequence, or mobile_input_text, and no prerequisites or exclusions. Usage is only weakly implied by the word 'combination'.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond that: digit tokens are pauses rather than a chord, x,y tokens are taps, plus signs create pause-free touch combos, and stepped.checks polls for a UI node before continuing.

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 four dense sentences with no filler. It front-loads the core action and then spends each remaining sentence on high-value syntax or execution-mode 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?

An output schema exists, so return values need not be described, and the annotations cover the safety profile. The description adequately explains the complex sequence and stepped-execution behavior, but it leaves gaps around source selection, gapMs usage, and when to use this tool versus sibling input tools.

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 only 33%, so the description must compensate. It gives essential meaning to the sequence grammar and to stepped.checks, which are otherwise opaque in the schema, though it does not explain gapMs, source, pollMs, or timeoutMs beyond what their names and schema defaults imply.

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: sending a timed sequence of Android keys and touchscreen taps in one call. It also distinguishes this from a simultaneous key chord by saying digits are millisecond pauses, not a chord, which helps separate it from sibling tools like mobile_input_key_combination.

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 usage for multi-action input in one call and explains the stepped.checks mode, but it never explicitly says when to choose this tool over mobile_input_key, mobile_input_tap, mobile_input_key_combination, or mobile_batch. The operational context is present, but alternative selection guidance is left to inference.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive input action, so safety is covered. The description usefully discloses that the gesture is synthesized as a zero-distance swipe, which explains why it exists as a distinct tool. It says nothing, however, about how the hold duration is controlled or what failure/side effects to expect, so it adds only modest behavioral context.

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, front-loaded with the core action and followed by the minimal targeting instruction. No filler, though the second sentence partially restates the schema's ref description rather than adding new 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. What is missing for a gesture tool is the hold-duration story (no mention of durationMs or its default/bounds) and any hint of when long press is preferable to tap or drag; the definition is adequate but leaves the agent to infer the defining 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 50%, and the description partially compensates by telling the agent to supply 'ref or x and y' (the ref-wins-over-coordinates rule is also in the schema). It never mentions durationMs, which is the parameter that actually defines a long press and has a non-obvious default of 800ms with a 200-10000ms range, leaving a meaningful gap.

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 (hold a touch at one point) and even explains the mechanism (swiping from the point to itself), which implicitly separates it from mobile_input_swipe and mobile_input_drag. It is clear what the tool does, though it never explicitly names the sibling tools it competes with (tap, double_tap).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence ('Pass ref or x and y') is targeting mechanics, not usage guidance. There is no statement of when a long press is the right gesture versus mobile_input_tap, mobile_input_double_tap, or mobile_input_drag, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=false, so the agent knows this is a state-changing, non-repeatable on-device operation. The description adds 'display-targeted' and 'explicit duration' but says nothing about what UI/app state the gesture affects, stale-ref failure modes, or permission needs.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both load-bearing, with the core action stated first and the ref-precedence rule second. There is no redundancy 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?

An output schema exists, so return values need no prose, and the precedence rule covers the trickiest ambiguity among 7 parameters. However, for a non-idempotent injection tool with stale-ref risk, the description omits failure behavior and where the gesture lands, leaving meaningful 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 57%, and the description compensates by stating a real semantic rule absent from the schema: startRef/endRef 'win over' start and end when both are supplied. It does not clarify displayId (framework vs SurfaceFlinger is only in the schema) or the durationMs default, so it is not fully compensating.

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: 'Inject a display-targeted touchscreen swipe with explicit duration.' An agent can tell it apart from mobile_input_tap or mobile_input_long_press, though the boundary with the sibling mobile_input_drag (which likely also expresses a move gesture) is not addressed.

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 when-to-use/when-not guidance and no alternative named; the agent is left to infer that a swipe differs from drag. The only routing-style statement is the startRef/endRef precedence, which is closer to parameter semantics than usage 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the agent knows this is a non-destructive, non-idempotent mutation. The description adds the staleness constraint ('latest UI read') and the coordinate-space semantics, but says nothing about error behavior when a ref is stale or a tap targets an off-screen location.

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, zero filler, with the action and coordinate space front-loaded and the ref-vs-x/y precedence rule immediately after. Every sentence carries distinct 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?

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. What remains thin is side-effect/failure context for a mutation tool (what a tap does if the ref is stale or the coordinates are outside the display), but the essentials for calling it correctly are 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 coverage is 60%, and the description partially compensates: it explains the x/y vs ref precedence and advises preferring ref over a node's raw center, which is guidance the schema does not contain (the schema only says ref 'wins over x and y'). The coordinate-space phrasing also clarifies displayId's 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?

States a specific verb and resource ('Inject a display-targeted touchscreen tap') plus the coordinate space ('logical display coordinates'). This is unambiguously the single-tap input tool, distinguishable from mobile_input_double_tap, mobile_input_long_press, and mobile_input_drag 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?

Gives clear operational context: the ref must come from 'the latest UI read,' and ref is preferred over x/y or a node's raw center. It does not, however, name when to reach for a sibling input tool (double_tap, long_press) instead, so it stops short of full alternative 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?

Annotations already declare readOnly=false, idempotent=false, destructive=false, openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context: that a ref causes a prior tap on that node, and that Unicode input is a known limitation that will be surfaced rather than silently swallowed. It does not say what happens to existing field content.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no filler, and the primary action is front-loaded before the ref precondition and the caveat. Every sentence carries distinct 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?

With an output schema present and annotations covering the safety/mutation profile, the description does not need to explain return values. It covers the action, the ref precondition, and the Unicode caveat, which is what an agent needs to call this 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 75%, so the baseline is 3. The description does add real meaning for ref (it triggers a tap before typing, not just a lookup key), which the schema only implies. It adds nothing for text length limits or displayId.

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?

Specific verb+resource: 'Type text through ADB's virtual keyboard', which is clearly distinguishable from the key-event siblings (mobile_input_key, mobile_input_key_sequence). It also discloses the Unicode constraint up front. It stops short of naming an alternative sibling when text entry won't work.

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?

'Pass ref to tap that node first' gives conditional usage guidance for one parameter, and 'Reports the Unicode limitation instead of hiding it' signals an expected failure mode. However, it never says when to prefer this over mobile_clipboard, mobile_input_key, or other input tools, so usage 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?

Rich behavioral disclosure beyond the annotations: emulator path uses 'adb emu geo fix' with a specific argument order, clear on emulator is unsupported, device path requires Android 12/API 31 and injects a GPS test provider, and fused clients may ignore that provider. This is exactly the kind of platform-specific caveat an agent cannot infer from readOnlyHint/destructiveHint.

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 tight sentences, each carrying a distinct platform fact, with no filler or repetition. It reads as dense reference prose rather than a front-loaded summary, but nothing is wasted.

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 platform-divergent mutation tool, the description covers the critical failure modes and prerequisites, and an output schema exists so return values need no explanation. It stops short of clarifying accuracy and validation rules for coordinates, which is the main remaining 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 coverage is only 20%, so the description must compensate, and it partially does by documenting the longitude-then-latitude ordering for the emulator path. It says nothing about accuracyMeters semantics/default behavior, the action enum default, or lat/long validity constraints, leaving a real gap.

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 title and opening establish a specific verb+resource ('Set or clear a mock location'), and the body clarifies the two supported actions with real mechanism detail. It does not explicitly contrast with a sibling tool, but the sibling list contains no overlapping location tool, so ambiguity is low.

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 usage contexts by splitting emulator vs device behavior and warns that clearing an emulator fix fails ('the console has no clear'), which is a genuine when-not-to-use signal. It never states when to reach for this tool vs any alternative, so guidance is mostly implicit.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is largely covered. The description adds the useful scheme-validation behavior, but says nothing about which app handles the intent, foreground changes, or failure behavior for a non-idempotent action.

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, zero filler, with the core action and the scheme restriction front-loaded. Every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be described, and the description covers the action, accepted schemes, and display targeting for a 3-parameter tool. Minor gaps remain around required device/serial handling and failure modes, but nothing essential to invoking 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 67%: serial and displayId are documented in the schema, while url carries only length bounds. The description adds the meaningful constraint that url must be http/https, partially compensating, but 2048-char limit and display semantics add nothing beyond the schema. Baseline 3 fits.

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 action ('Start ACTION_VIEW') and resource ('http or https URL'), and narrows scope to one logical display. It is distinguishable from siblings like mobile_app_launch or mobile_input_tap, though it never names an alternative sibling, so it stops 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?

The scheme restriction ('http or https... others rejected') implies when the tool is valid, but there is no explicit statement of when to prefer this over mobile_app_launch or other navigation-oriented siblings, and no prerequisites such as requiring an unlocked device.

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

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

Annotations declare a non-read-only, non-destructive, non-idempotent, closed-world mutation; the description adds real behavioral detail beyond that, notably that 'free' delegates to the accelerometer and that 'get' returns 'free' or 'lock N' plus observedRotation when known. It leaves out any note on permission requirements or what happens to a locked display across reboots/disconnects.

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, each carrying distinct information (scope, lock/free semantics, get semantics). The read-or-write framing is front-loaded and nothing is padded.

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 the return-value sentence is bonus rather than a requirement. Scope, action semantics, and the display-ID caveat (carried in the schema) together cover what an agent needs; only behavioral edge cases and the exact serial requirement (schema-only) are left unaddressed here.

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 only 50% (serial and displayId are documented; action and rotation are not). The description compensates by enumerating the action values and tying rotation 0-3 specifically to the lock action, which the schema's bare 0-3 enum does not explain.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair and resource: 'Read or set user rotation for one logical display.' No sibling tool touches rotation, and the display scoping ('one logical display') is stated up front, so an agent can place it immediately.

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 disambiguates the three actions concretely: 'lock' consumes rotation 0-3, 'free' hands control to the accelerometer, 'get' reports state. That is clear per-action context, though it does not explicitly frame when a caller should prefer get vs lock vs free (e.g. before asserting orientation in a test).

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent), so the agent knows this is a non-destructive write. The description adds the 'offsetMs from record start' framing but omits behaviors like what happens if no recording is active, whether labels must be unique, or ordering guarantees.

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?

A single, front-loaded sentence with the core action stated first and no wasted words. The trailing 'analyze/focus/logcat' reference is slightly loose (not exact tool names) but still compact and informative.

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 simple mark operation is mostly covered. Still missing the operational prerequisite that a recording must be running and that recordId must originate from mobile_record_start, which matters for a 3-required-param write 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 coverage is 67%, with serial and label well described in the schema; recordId carries only a format/pattern. The description adds little param detail beyond clarifying label semantics implicitly via 'labeled timestamp'. The mention of 'offsetMs' refers to a computed value, not a parameter, so it doesn't clarify any input.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete action ('Attach a labeled timestamp') plus the mechanism ('offsetMs from record start'), so an agent understands this records a timeline marker within an active recording. It doesn't explicitly name or contrast itself against siblings like mobile_record_start/stop, but the purpose is clearly distinguishable from them.

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?

'for later correlation with analyze/focus/logcat' implies why you'd use it, giving implied usage context. However, it never states the key precondition (a recording must be active, recordId from mobile_record_start) or when-not to use it, leaving the agent to infer.

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

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

Annotations cover safety (non-readOnly, non-destructive, non-idempotent, openWorld), so the bar is lower. The description still adds real operational context beyond annotations: capture is non-blocking and only one active session per (serial, displayId) is allowed. It omits what a session produces and how it is terminated.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, zero filler, with the non-blocking behavior front-loaded and the concurrency constraint as the closing caveat. Every clause carries 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?

An output schema exists so return values need not be explained, and annotations carry the safety profile. The description supplies the key behavioral traits (async, single-session-per-target), but does not mention lifecycle pairing with mobile_record_stop or mobile_record_mark, a minor gap for a session-starting 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 coverage is 100%, so both serial and displayId semantics (exact ADB serial, framework logical display ID vs SurfaceFlinger ID) are already fully documented in the schema. The description adds no parameter-level detail, making the baseline 3 correct.

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: 'Start a non-blocking screenrecord on one logical display.' The 'non-blocking' qualifier and 'one logical display' scope meaningfully distinguish it from a generic record sibling, but no sibling (e.g. mobile_screen_record, mobile_record_stop) is named for explicit contrast.

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?

'so input tools can run during capture' tells the agent the condition that selects this tool over a blocking capture. No exclusion or explicit pointer to mobile_screen_record / mobile_record_stop, so it stops short of full alternative 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?

Annotations declare the safety profile (readOnly=false, openWorld=true, idempotent=false, destructive=false), so the description only needs to add context – and it does: it discloses the SIGINT termination mechanism, that the MP4 is copied into the artifacts store, and that marks with offsets are returned. It omits failure modes (unknown recordId, already-terminated session) and whether artifact retention is bounded.

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?

A single front-loaded sentence with three sequentially ordered clauses, each carrying information (mechanism, side effect, return). No padding, though it is terse enough that some behavioral context is squeezed out.

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 the return value need not be explained in depth, and the description still flags that marks with offsets come back. For a two-parameter stop tool, the main remaining gap is the lifecycle linkage to mobile_record_start and error behavior, not the core call contract.

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 only 50%: 'serial' is documented but 'recordId' has just a UUID format/pattern with no textual meaning. The description adds nothing about either parameter – it doesn't say where recordId comes from (presumably mobile_record_start) or why serial must be exact when multiple devices exist, which is the exact gap the low coverage leaves open.

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 (stop), the resource (screenrecord), and the concrete outcome (MP4 pulled into artifacts, marks with offsets). An agent can distinguish it from mobile_record_start and mobile_record_mark by name, though the description never names those siblings 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 explicit when-to-use or prerequisite guidance. The pairing with mobile_record_start and mobile_record_mark is only inferable from the wording ('stop screenrecord', 'return marks'), and nothing states what to do if the recording was never started or already stopped.

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

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

Annotations declare the safety profile, and the description adds genuinely useful behavior beyond them: the >1280px downscaling rule and the coordinateScale conversion for downstream input tools. It does not explain the readOnlyHint=false flag for what reads like a capture operation (likely artifact persistence), a minor gap.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences with no filler, and the core operation is front-loaded before the downscaling and coordinate-mapping details. Every sentence carries information relevant to correct invocation.

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 description covers the key non-obvious behaviors (downscaling, coordinate conversion, ID resolution). The only real omission is what saveArtifact does, which leaves a small completeness 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 coverage is 67% and the schema already documents serial and displayId well, including the logical-vs-physical ID distinction. The description echoes the physical-ID resolution idea but does not clarify the undocumented saveArtifact parameter, so it adds only marginal meaning over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.