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

With no annotations, the description carries the full burden and does so: it discloses ordering, the 20-action cap, non-atomic execution ('stops at the first failure — earlier actions stay done'), and the response shape ('per-action results with timing and error envelopes'). The non-atomicity and no-blind-replay rules are exactly the behavioral traits an agent needs before invoking a mutating batch tool.

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

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

The size is justified by the action vocabulary that would otherwise be undocumented, and the batch constraint plus failure semantics are front-loaded. Structure is weak, though — a single long run-on sentence of comma-separated enumerations makes it harder to scan than a short bulleted action list would be.

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

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

For a 20-item mutating batch tool with no annotations and no output schema, the description covers the essentials: allowed actions, ordering, failure behavior, response envelope at a summary level, and post-batch observation. Missing pieces are the `device` parameter and any note on whether a failed batch can be resumed or selectively re-run.

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 0% and `actions` is a bare array of untyped objects, so the description must compensate — and it largely does, spelling out the payload shape for tap (x/y fractions, text/id/desc with nth, or ref+snapshot_id), swipe, long_press, double_tap, type, key, open_app, close_app, open_url, notifications, wait, and wait_for. The gap: the `device` parameter is never mentioned, and observe is described only for 'ui'/'screenshot'/'both' while the enum also allows 'none'.

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

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

Opens with a specific verb+resource+scope: 'Run a batch of up to 20 actions in order on the device,' then enumerates every supported action type with its payload shape. The batch framing implicitly but clearly distinguishes it from the singular siblings (previewapk_tap, previewapk_swipe, previewapk_type_text, previewapk_press_key), so an agent can pick it without reading schemas.

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

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

'NEVER replay a batch whose outcome you don't know; observe first' is an explicit when/when-not rule, and the observe parameter guidance tells the agent to attach the screen after the batch. It stops short of stating when to prefer this tool over the one-action siblings (e.g., multi-step sequences vs. a single tap with immediate verification).

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the 10 MB file limit, /sdcard restriction, mock location persistence until cleared, locale relaunch need, reboot duration and data survival, recording-save behavior, and the absence of clipboard control.

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

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

The description is compact for a nine-action tool and front-loads the overall purpose before listing each action with only the details needed to use it correctly. The final clipboard exclusion is also useful and wastes no 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?

Given the absence of annotations and output schema, the description covers nearly all operational behavior an agent needs, including limits and side effects. It does not describe return values for actions like list_files or pull_file, and it leaves the device parameter unexplained, which are minor but real gaps.

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

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

The description adds substantial meaning beyond the 56%-covered schema: timezone examples, BCP 47 locale examples, default package behavior, location mock semantics, file size limits, list_files default folder, and reboot side effects. The only notable gap is the 'device' parameter, which is never explained.

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

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

The description clearly frames the tool as device controls for QA and enumerates the specific supported actions, including timezone, locale, location, file operations, and reboot. It is highly distinguishable from interaction siblings like tap or swipe, though it does not explicitly contrast itself with previewapk_use_device or other device-management tools.

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

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

Usage context is clear for each action: push_file for test fixtures, set_location creates a mock fix until cleared, set_locale is Android 13+ per-app language and may require app relaunch. It provides practical when-to-use cues but does not explicitly state when to choose this tool over sibling tools.

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

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

With no annotations, the description carries the full burden. It does disclose useful behavior: the report is 'read and tallied by the team that builds it' and that one call suffices with any subset of fields. However it omits whether the submission persists, whether a response is returned, or whether a session is required.

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

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

Core purpose and the field semantics are front-loaded, but the motivational framing ('you are one of the few who actually use it', 'the wishes of working agents are the roadmap') is rhetorical padding that doesn't help an agent invoke the tool correctly.

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-param, optional-all feedback tool with no output schema or annotations, the description is largely sufficient: it covers purpose, most fields, and timing. Gaps are the unexplained 'device' parameter and the absence of any return/confirmation 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 coverage is only 17% (just the rating field), so the description must compensate. It does: it defines broke, worked, wish and workaround with concrete meanings, covering 4 of the 6 parameters. Only 'device' is left unexplained, and rating is covered by the schema.

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

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

States a specific verb+resource ('File a field report about THIS tool') and enumerates the report's dimensions (broke/worked/wish/workaround). It is clearly distinct from the device-control siblings like previewapk_tap or previewapk_screenshot. Minor ambiguity in 'THIS tool' (the feedback tool vs. the whole previewapk server), but the intent is recoverable.

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

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

Explicitly says when to file ('before you stop the session, while the details are fresh') and clarifies the calling pattern ('One call, any subset of fields'). No alternatives exist among siblings, so no exclusion is needed, but it doesn't state any condition under which you should NOT file.

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

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

With no annotations, the description carries the load well: it discloses that counts are server-composed, that the report is persisted in the portal and session archive, and that end_session defaults to false so the phone keeps running under the 15-minute idle rule. It does not cover repeat-call behavior or failure handling, which keeps it short of a 5.

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

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

Front-loaded with the action and the return value, then the constraints. Dense but not padded — each sentence states a rule or a hazard. Slightly long, and the portal/archive detail is lower priority than the count-provenance warning it sits next to.

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

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

No output schema exists, and the description adequately explains the one meaningful return value (message_for_human, to be relayed verbatim) plus server-side persistence. For a low-complexity, 4-param filing tool this is nearly complete; only 'device' and guidance on choosing verdict are left to the schema.

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

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

Schema coverage is 75%, so baseline is 3; the description earns a bump by explaining the real-world consequence of end_session (session keeps running vs. phone stops now, plus the wording change), which the schema's one-line description does not convey. The 'device' parameter is never addressed in the description and relies entirely on the bare schema entry.

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 — 'File the wrap-up when your work on this session is done' — and names exactly what comes back ('get back message_for_human'). It also explicitly separates itself from the closest sibling: 'finish is the human's summary, feedback is the tool team's.'

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

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

Gives an explicit trigger ('when your work on this session is done'), routes the agent to previewapk_feedback for the other kind of report, and spells out the conditional for end_session=true ('only when the human should get the session-record wording and the phone should stop now'). The when-not is as clear as the when.

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

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

With no annotations, the description carries the full burden and does add real context: the link is view-only, minted at session start, and invalidated when the session ends, and driver_note signals whether the user took control. It omits permissions/auth needs, rate limits, and whether calling it has side effects.

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 sentence with the primary return value front-loaded and parenthetical qualifiers doing useful work. It is dense but every clause (view-only, minted at start, dies at end, driver_note meaning) adds 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?

There is no output schema, so the description must convey the return payload; it names the share link and driver state but not the shape or other fields beyond driver_note. Combined with the unexplained 'device' parameter, an agent has enough to call it but not a full picture.

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 parameter 'device' has 0% schema description coverage and is never mentioned in the description, so its meaning (device id? name? optional targeting?) is entirely undocumented. With one undocumented parameter, the description fails to compensate for the coverage 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 names the resource returned — the live session's share link plus driver state — which is specific and clearly distinct from siblings like previewapk_get_logs, previewapk_status, or previewapk_screenshot. The retrieval verb is only implied by the tool name rather than stated, but an agent can still tell what this tool yields.

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

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

There is no explicit when-to-use guidance or alternative named. The description notes the link is view-only and session-scoped, which hints at lifecycle, but it never says when to call this versus previewapk_status, which also exposes driver/session state.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that logs remain readable after session end via a saved tail of the last session, which is real added context. However, it says nothing about defaults (e.g., 100 lines), retention limits, or whether the log is cumulative across relaunches.

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

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

Three sentences, front-loaded with what the tool returns, then usage, then the session-end caveat. Every sentence contributes, though the phrasing is slightly conversational rather than maximally tight.

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

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

For a read-only log tool with no annotations and no output schema, the description covers what is returned and the post-session availability, which is the essential context. It leaves gaps on the filter parameters and default behavior that an agent would need to invoke it well.

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 40% (lines, device and errors_only are undocumented), and the description mentions no parameters at all — it never explains filtering by line count, device, or errors-only mode. With 5 parameters and low schema coverage, the description fails to compensate for the gaps.

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 (the attached app's debug log / logcat) and enumerates the content it surfaces: prints, warnings, errors and crash traces. An agent can immediately tell this apart from siblings like previewapk_hierarchy, previewapk_screenshot or previewapk_status, which cover different artifacts.

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

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

Explicitly says when to reach for it: 'Check it after actions and whenever something misbehaves: a crash's exact reason is here.' It also clarifies a non-obvious edge case (works after the session ends via the saved tail). No when-not guidance or named alternatives, but no sibling duplicates this capability, so the routing gap is minor.

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

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

With no annotations, the description carries the full burden. It does disclose the core behavioral trait — that control is transferred between agent and human — but says nothing about whether the call blocks, what happens to the session while the user drives, or how the agent should behave afterward.

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 compact sentence with a parenthetical example; the core handoff concept is front-loaded and no sentence is wasted. Slightly dense due to the metaphor, but structurally sound.

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

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

With no annotations and no output schema, the description should say more about what happens after handoff — whether the call returns immediately, how the agent regains control, and what 'device' selects. The core behavior is covered but surrounding context is thin.

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 compensate. It explains both values of the required 'to' parameter meaningfully, but the optional 'device' parameter is entirely unaddressed, leaving half the parameters 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?

The description states a specific action ('pass the wheel mid-session') and clarifies the two directions of control transfer. It is distinguishable from sibling device-control tools, though the resource being handed off (session control) is conveyed through metaphor rather than named directly.

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

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

It gives a concrete when-to-use example ('after you've verified a feature') and explains what each enum direction achieves. It stops short of naming when not to use it or pointing at alternative siblings, so it lands below full marks.

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

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

With no annotations, the description carries the burden and does disclose the key behavioral trait: this returns a structured tree rather than pixels and is 'much faster and cheaper' than a screenshot. It does not state that the operation is non-mutating, nor any error/default behavior, but the cost model and return nature are substantive context beyond a bare purpose statement.

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

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

Three tightly packed sentences with zero waste: the resource and return shape come first, the performance rationale second, and the alternative routing last. Nothing is redundant 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?

There is no output schema, so the description correctly takes on the job of enumerating return fields, which it does thoroughly. The only meaningful hole is the unexplained 'device' parameter, which is the sole input.

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% and there is one parameter ('device') that is never mentioned or explained in the description. The description must compensate for the coverage gap and does not, so the agent gets no guidance on what device identifier to supply or what the default is.

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 ('Get the current screen as a UI element tree') and enumerates the returned fields (class, text, content-desc, resource id, bounds, center coordinates, state flags). It explicitly contrasts itself with previewapk_screenshot ('instead of pixels'), so an agent can tell the two apart without opening a 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 explicit when-to-use conditions ('find elements, read values, check state' for navigation and assertions) and names the alternative with its own use case ('Use previewapk_screenshot for visual checks (layout, overlap, images)'). The routing decision is fully specified.

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

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

No annotations exist, so the description carries the full burden; it discloses the return contents, which is the key behavioral fact for a zero-argument discovery tool. It does not discuss auth requirements, rate limits, or whether the list is paginated, but for a simple read-only enumeration the disclosed output shape covers most of what an agent needs.

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

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

Two tight sentences with no waste: the first declares the resource and its returned fields, the second front-loads the ordering instruction before the chaining detail. Every clause earns its place.

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

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

With no output schema and no annotations, the description compensates by listing the returned fields and explaining the role of the result in the wider tool chain. An agent has everything needed to call it correctly and use the output.

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 the baseline is 4. The description adds genuine cross-tool semantics by explaining that the chosen device's name or id becomes the 'device' argument on the other tools, which is information no schema field conveys.

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

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

States a specific verb and resource ('List the devices on this account') and enumerates the fields returned (name, id, profile, Android version, status, attached app). It does not name the nearby sibling previewapk_use_device, which also deals with device selection, so sibling differentiation is only implied rather than explicit.

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 a clear trigger condition ('when the account may have more than one device') and tells the agent to call it FIRST, plus how to chain the result into other tools. It never states a when-not case or names an alternative (e.g. previewapk_use_device) for when a device is already known.

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

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

With no annotations, the description carries the full burden and does well: it discloses the stale_snapshot failure mode, the cost/performance tradeoff versus siblings, and that screenshot=true adds image output. It doesn't explicitly state read-only semantics or whether the snapshot is cached, but the read nature is strongly implied by 'Read'.

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?

Information-dense with the core purpose front-loaded in the first clause, and the follow-up workflow and cost tradeoff placed after. The first sentence is a long run-on packed with parenthetical detail, but every clause carries useful signal.

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

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

There is no output schema, so the description must explain the return value – and it does, listing the element fields, reading order, and the compact-text companion form. Combined with the documented failure mode and follow-up usage, an agent has everything needed to call and interpret it.

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% – `device` has no description anywhere and `screenshot` appears only as a bare boolean with a default. The description rescues `screenshot=true` and clarifies that `scale` applies only when screenshot is true, but the `device` parameter remains completely undocumented in both places.

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

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

States a specific verb and resource ('Read the current screen as a compact numbered snapshot') and enumerates exactly what comes back (foreground app, keyboard, elements with ref/type/text/bounds). It also positions itself against siblings by being 'cheaper than a screenshot and cheaper than the full hierarchy', which maps cleanly onto previewapk_screenshot and previewapk_hierarchy.

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

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

Explicitly recommends this over a screenshot and over the full hierarchy, and gives a concrete follow-up workflow (keep snapshot_id, pass ref + snapshot_id to previewapk_tap, expect stale_snapshot if the screen changed). It stops short of stating a when-not condition, e.g. when the full hierarchy is actually required.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it is silent on whether the keypress targets the active device or the `device` param, what the call returns, or any side effects (navigation, focus loss, app changes). Only the keycode values are disclosed.

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 verb first and the keycode mapping immediately after. Every token earns its place; there is no filler.

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

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

With no annotations, no output schema, 2 parameters at 0% schema coverage, and no description of the `device` parameter or post-keypress behavior, an agent lacks the context to call this tool confidently in a multi-device session.

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 compensate. It does document meaningful `keycode` values (4=Back, 3=Home, 187=Recents, 66=Enter, 67=Delete), which is genuinely useful, but it never states that the field takes a raw Android keycode integer or explains the `device` parameter at all.

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 ('Send') and resource ('Android keycode') with the accepted values enumerated, which clearly separates it from siblings like previewapk_tap, previewapk_swipe and previewapk_type_text. It does not explicitly name those siblings, 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 description says what the tool does but gives no guidance on when to use it versus tapping or typing text, no prerequisites, and no indication of which device it targets. Usage must be inferred entirely from the tool 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?

With no annotations, the description carries the full burden and does so: it discloses hot-swap-without-reboot behavior, dedupe of identical bytes, downgrade refusal, and that replace=true uninstalls first and DELETES app data. Side effects and destructive consequences are spelled out rather than implied.

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

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

Front-loaded with the core action and then ordered by device state, so the reader hits the branching logic immediately. Dense but every clause adds operational meaning; the parenthetical return-value hints are slightly compressed but not wasteful.

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

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

No output schema exists, yet the description still explains the return shape (parsed app info, swapped=true, deduped=true). The only real gap is the unexplained 'device' parameter, which matters when multiple devices are in play.

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 description enriches 'replace' with the downgrade scenario and its data-deletion consequence, beyond the schema's own note. However, the 'device' parameter is undocumented in both the schema and the description, leaving one of three parameters unexplained.

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 ('Upload an APK file from this machine to the device') and immediately branches by device state, which no sibling tool does. It explicitly names previewapk_start as the follow-up, distinguishing it from the rest of the previewapk family.

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

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

Gives explicit when-paths: device OFF → becomes attached app then call previewapk_start; device RUNNING with the wheel held → live hot swap. It also states the refusal condition (older versionCode → version_downgrade) and the escape hatch (replace=true), leaving nothing 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?

With no annotations, the description carries the behavior burden and does add real value: it discloses that transfers are resumable from the interruption point and that omitting rec_id falls back to the session's latest finished recording. It omits overwrite behavior when the file exists, size limits, and permissions.

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, zero filler, with the action and destination front-loaded and the resumability/default notes following in a natural order.

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

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

No output schema or annotations exist, so the description must stand alone; it covers the save target and resumability but leaves the device parameter, overwrite semantics, and behavior when no recording is available unaddressed.

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%; path and rec_id are already documented in the schema. The description adds the nuance that rec_id defaults to the session's *latest finished* recording, but the device parameter is unexplained in both schema and description, so it doesn't compensate fully.

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 (download) and resource (a finished recording's MP4) plus the destination (local file path), which cleanly separates it from sibling record_start/record_stop and the screenshot/observe tools.

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

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

The phrase 'finished recording' plus the omission rule for rec_id gives clear context for when to call it, and the schema note ties rec_id to record_stop. It stops short of explicitly naming record_stop as the prerequisite or stating what to do if no finished recording exists.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the 180-second cap and automatic stop/save on session end or reboot, but it does not mention permissions, whether multiple recordings can coexist, where recordings are stored, or how device selection works.

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, front-loaded with the action and cap, followed by the stop/download lifecycle and auto-save behavior. There is no wasted wording.

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

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

The description covers the recording lifecycle and key constraints, which is useful given the lack of annotations and output schema. However, it does not resolve device selection or the optional name behavior, so it is adequate but not 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?

The schema documents only the name parameter, and the description adds no meaning for it beyond the existing label description. The device parameter is undocumented in both the schema and the description, including whether it is optional or which device is used by default, leaving a meaningful gap for a two-parameter tool.

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 recording the device screen to an MP4. It also names the recording cap and distinguishes the lifecycle from previewapk_record_stop and previewapk_record_download, so the tool is easy to identify among siblings.

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

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

Clearly explains the lifecycle: start here, then stop with previewapk_record_stop, then download with previewapk_record_download. It does not explicitly compare against previewapk_screenshot or previewapk_observe for still-image capture, so it is strong but not fully exclusionary.

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

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

With no annotations, the description carries the full burden and does well: it discloses the server-side transfer, the index fields (rec_id, size, duration), and persistence after session end. Gaps remain on failure modes (no recording running), whether the call blocks until transfer completes, and any permission requirements.

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

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

Two sentences, action first, side effect second, routing hint attached to the effect it relates to. No filler and nothing buried.

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

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

For a one-param, no-output-schema stop tool the description covers the effect, the resulting artifact, and the next step. Only the undocumented 'device' parameter and error behavior keep 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?

The single 'device' parameter has 0% schema description coverage and the description never mentions it — an agent cannot tell whether it targets the current device implicitly or must be supplied. With only one optional param this is a small but real gap, since behavior likely differs when a device is passed.

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 the running recording') that cleanly separates it from the sibling previewapk_stop, and adds the concrete effect (MP4 pulled to server, indexed). An agent can identify this as the recording-termination tool 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?

Names the follow-up tool explicitly ('download it with previewapk_record_download') and clarifies that stopping is non-destructive to availability ('Recordings stay downloadable after the session ends'), which removes the main hesitation about calling it. It does not state what happens if no recording is active, nor any prerequisite such as a prior previewapk_record_start.

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

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

No annotations are provided, so the description carries full burden. It discloses useful traits beyond the schema: the ~2 second latency and that no reboot is required, which tells the agent the session survives. It omits what happens if no session/app exists and whether state is preserved, leaving real gaps for a state-changing tool.

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

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

Two tight sentences, front-loaded with the core action and followed by the conditions and cost. Zero filler, every clause earns its place.

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

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

For a single-param, no-output-schema tool the description covers purpose, triggers, and timing adequately. It leaves the device parameter unexplained and gives no error behavior (e.g., no active session), which are the remaining 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?

There is one parameter (device) with 0% schema description coverage, so the description must compensate and does not — the device argument is never mentioned. With low coverage and no explanatory text, the agent gets no syntax or scoping guidance for the 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 names a specific action (bring the session's app back to the foreground) and its outcome, with concrete triggering scenarios. It distinguishes the operation from cold-start siblings by framing it as a return to foreground, but never names an alternative like start or use_device 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?

It gives clear when-to-use context: after Back exits to the launcher, or the app crashed or was closed. This is more than implied usage. It offers no exclusions or explicit routing against siblings, which keeps it short of a 5.

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

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

With no annotations, the description carries the full burden and does so: it discloses the portal side effect (device card shows 'Your agent needs you'), the returned field (message_for_human), the handback mechanism via wait_for's result, and the prerequisite of a live session. That is unusually rich behavioral disclosure for a mutation-adjacent tool.

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

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

The opening clause is front-loaded with the purpose, and each subsequent sentence carries distinct operational content (side effect, relay instruction, parking instruction, prohibition). It is dense but a little long; the parenthetical note on the handback and the live-session requirement could be tightened.

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

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

There is no output schema, and the description explicitly explains the return value (message_for_human) and what the subsequent wait_for call yields. For a 2-parameter coordination tool, an agent has everything needed to call it correctly, with only the device parameter left to the schema.

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

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

Schema coverage is 50%: 'reason' is documented in the schema (short line, ~200 chars) and the description implies its content ('what the human needs to do'), but the 'device' parameter is never mentioned in either the description or the schema. The description therefore only partially compensates for the coverage 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 verb and resource ('Ask the human for a step only a human should do') and enumerates concrete triggering cases (password, 2FA, payment, CAPTCHA, irreversible actions). It is clearly distinguishable from automation siblings like previewapk_tap or previewapk_act.

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

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

It gives explicit when-to-use cases, a follow-up workflow (relay message_for_human VERBATIM, then park on previewapk_wait_for with condition='driver'), and a hard exclusion: never have the human paste secrets into chat. Alternatives and sequencing are spelled out rather than implied.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: the download auto-resumes on a cut connection, and scale trades fidelity for transfer size. It still omits the return medium, whether the device parameter is required, and any latency/rate characteristics.

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

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

Three sentences, front-loaded with the core purpose, and every sentence carries information. A minor redundancy exists in restating the scale tradeoff that the schema already implies.

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 2-parameter tool with no output schema, the description covers purpose, usage, and transfer behavior, and gestures at the return value ('an image you can see'). The unexplained 'device' parameter is the 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 50%: 'scale' is defined in the schema, and the description adds a weak-network scenario ('pass scale=0.5 ... for a quarter-size transfer'), which is marginal new meaning. The 'device' parameter is undocumented in both the schema and the description, leaving the coverage gap uncompensated.

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 ('Capture the device's current screen as an image') and signals its relationship to the sibling previewapk_hierarchy ('the real screen — it agrees with the hierarchy'). The differentiation is present, though it stops short of explicit 'use X instead of Y' routing.

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 it to verify your changes look right' gives a clear use context matching the 4-level rubric. There is no guidance about when NOT to use it or which sibling to prefer when the agent just needs the textual tree (previewapk_hierarchy).

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

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

With no annotations, the description carries the full burden. It usefully discloses that in driver='user' mode the agent's input is refused and points to where session links come from, but it omits preconditions, what state a start creates or overwrites, permission requirements, and what happens if a session already exists.

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 front-loaded sentences with little waste: purpose first, then the driver semantics, then the return/next-step guidance. All earn their place, though the final sentence about session_url is slightly tangential to the start action itself.

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

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

No output schema or annotations exist, so the description must stand alone. It covers the action, the key parameter's semantics, and the high-level return flow (links info), which is enough for correct invocation, though the 'device' parameter and the exact return shape remain unspecified.

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

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

Schema description coverage is 0%, so the description must compensate. It does an excellent job on the driver enum (clearly defining agent vs user behavior), but the required 'device' parameter is never explained — no format, ID source, or relationship to previewapk_list_devices — leaving half the parameters semantically 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?

"Start a preview session for the device's attached app" is a specific verb+resource that clearly distinguishes it from previewapk_stop and the action siblings (tap/swipe/type). However it never explicitly clarifies its boundary against previewapk_relaunch or previewapk_use_device, both of which also relate to getting an app running, so differentiation from those siblings is left to inference.

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

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

The description explains the agent vs user driving modes well, but that is parameter selection guidance rather than when-to-call-this-tool guidance. There is no statement of preconditions (e.g. does a device need to be selected first via previewapk_use_device) or when to prefer this over relaunch, so usage is only implied.

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

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

With no annotations, the description carries the full burden — and it does so well, disclosing non-obvious state transitions: the handoff block appears while a request is pending, finish_report appears only once filed, and handback_note + resumed:true appear exactly once on the first read after handback. That 'exactly once' consumption semantics is critical and would otherwise cause agents to miss the handback. What it lacks is any statement of whether the read itself is side-effecting or what happens if you poll before a handoff exists.

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?

It is front-loaded with the core purpose and contains no filler sentences. However, the second half is a single dense chain of colons, em-dashes and parentheticals that takes real effort to parse; splitting the handoff / finish_report / handback semantics into short statements would cost nothing and read far better.

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

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

No output schema exists, so the description must explain the return payload — and it covers the important parts (session status, driver, links, handoff block contents, finish_report, handback_note). Minor gaps remain: the meaning of session status values is not defined, and 'links' is left for the agent to reconcile with previewapk_get_links.

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% (the single optional `device` param is documented in-schema), so baseline is 3. The description's only addition is the plural 'device(s)', which hints that omitting `device` returns all devices — useful but marginal, and it never confirms scoping behavior.

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?

It names a specific resource (the owner's PreviewAPK device state) and enumerates the fields returned: attached app, session status, driver, links. The purpose is unambiguous, but the heavy emphasis on the handoff/handback payload obscures the simple 'read current status' framing that would separate it most cleanly from siblings like previewapk_device or previewapk_list_devices.

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 one concrete trigger: call it to learn that a handback happened ('no chat message needed'). It never states when to use this instead of previewapk_device, previewapk_list_devices, or the handoff/finish tools, and offers no exclusions or ordering guidance, so usage is only implied for most cases.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the session link dies with the stop, which is important destructive context, but it does not explain whether device state is retained, whether the action is reversible, what permissions are required, or what happens to the optional device parameter.

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

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

The core instruction is front-loaded and brief: "Stop the session. The session link dies with it." However, the parenthetical about previewapk_feedback is unrelated to invoking previewapk_stop and consumes space without helping the agent decide or act. The useful content is concise, but the included sibling advertisement reduces focus.

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

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

The description covers the basic action and one key consequence, but with no annotations, no output schema, and an undocumented optional parameter, it leaves significant gaps. It does not explain how the device parameter affects the operation, what the tool returns, or how this stop differs from other session-ending tools in the sibling set.

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 has one optional parameter, device, with 0% schema description coverage and only the type "string" documented. The description never mentions the device parameter, so it adds no meaning about what the parameter selects or how it affects which session is stopped. With low schema coverage, the description should compensate but does not.

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: "Stop the session." It also clarifies the immediate consequence that the session link dies. However, it does not distinguish this action from sibling tools such as previewapk_finish or previewapk_handoff, which may also end or transition a session.

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

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

The description gives no guidance on when to use this tool versus alternatives like previewapk_finish, previewapk_handoff, or previewapk_record_stop. It implies stopping the session but provides no exclusions, prerequisites, or decision criteria for an agent choosing among similar lifecycle tools.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the duration default (300ms), but says nothing about device targeting (a real concern given sibling tools previewapk_use_device/list_devices), whether the gesture is synchronous, or what happens on 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?

Two compact sentences, front-loaded with the coordinate semantics and the optional/default duration. No filler; every clause carries information the schema lacks.

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 gesture tool with no annotations and no output schema, the description covers coordinate semantics adequately but omits device selection and execution behavior. It is minimally sufficient rather than 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 coverage is 0%, so the description must compensate. It does well for five of six parameters by defining x1/y1/x2/y2 as normalized 0..1 fractions and giving duration_ms an optional flag plus default, but the 'device' parameter is left completely undocumented in both schema and 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?

States a specific verb (swipe) and resource (screen gesture) with the exact coordinate convention '0..1 fractions', which is the crucial detail for this tool. It is clearly distinct from the tap/press_key/type_text siblings by the gesture name, though it never explicitly differentiates itself 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?

There is no statement of when to use a swipe versus alternatives like previewapk_tap or previewapk_tap_text, nor any prerequisite (e.g. an active device). Usage must be inferred entirely from the tool 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?

With no annotations, the description carries the burden well: it discloses the re-find-before-tap safety behavior and the concrete failure mode ('fails with stale_snapshot instead of tapping the wrong thing'), plus the session precondition. Gaps remain on return values and on what happens if both coordinate and ref arguments are supplied.

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?

Tightly front-loaded: the action first, then the two targeting modes, then the safety guarantee. Every clause contributes information an agent needs; nothing is 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?

No annotations and no output schema, so the description must cover behavior alone, and it covers failure modes and preconditions. However, with 0 required parameters it never says what happens if neither coordinates nor a ref are supplied, and the 'device' parameter is unaddressed in both schema and description.

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?

Adds substantial meaning beyond the 40%-covered schema: x/y are defined as 0..1 resolution-independent fractions (the schema says only 'number'), and ref/snapshot_id are explained as a coupled pair tied to a previewapk_observe snapshot. The 'device' parameter and the precedence between coordinate mode and ref mode are left unexplained.

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

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

Opens with a specific verb+resource ('Tap the screen') and immediately enumerates the two supported targeting modes, so an agent knows exactly what the tool does. It implicitly contrasts with the ref-based flow of previewapk_observe but never names siblings like previewapk_tap_text or previewapk_act, so the differentiation is not fully explicit.

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?

Clearly states the two usage paths (normalized coordinates vs. ref+snapshot_id from previewapk_observe) and names the sibling that produces the ref. It also gives the gating condition 'Requires an agent-driven session', which tells the agent when the call is not available, but it does not exclude or compare against tap_text/act.

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

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

With no annotations, the description carries the full burden and does well: it discloses match precedence (exact before substring), the ambiguity behavior (returns ambiguous_target with candidates rather than guessing), and how the tap point is derived (element center from the UI hierarchy). It omits what happens on no-match and says nothing about device selection or permissions, which keeps it from a 5.

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

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

Three dense sentences, front-loaded with the core action, then edge-case behavior, then the sibling preference. No filler and every clause adds decision-relevant 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 a three-parameter UI action tool with no annotations and no output schema, the description covers matching, ambiguity, and tap-point resolution well enough to call safely. The unexplained `device` parameter and the undefined no-match outcome are the remaining 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 0%, so the description must compensate. It explains `text` semantics (exact preferred, else substring) and `index` (pick among matches), which is genuinely useful, but the `device` parameter is never mentioned, leaving one of three parameters undefined in both schema and 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?

States a specific verb and target ('Tap the element whose visible text matches') and immediately contrasts with the sibling coordinate-tap tool, so an agent can pick correctly without opening any schema. The matching rule and ambiguity handling further pin down exactly what the tool does.

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

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

Explicitly routes the agent: 'prefer this over coordinate taps whenever the target has text,' which names the alternative (previewapk_tap) and the condition that selects this tool. It also tells the agent to supply index when several elements match, covering the main decision point at call time.

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

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

With no annotations, the description carries the full burden, and it does disclose a genuine behavioral trait: the call fails when nothing is focused rather than typing into the void. That said, it says nothing about default device selection, whether text appends or replaces, or how the failure surfaces to the caller.

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 action and the precondition. The phrase 'instead of typing into the void' is colorful but it earns its place by explaining the fail-fast behavior, so there is little waste.

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

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

For an interaction tool with no annotations and no output schema, the description covers the action and one failure mode but omits device targeting, expected return, and behavior on unfocused fields beyond the failure note. Adequate but with clear 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 0% for two parameters, so the description must compensate — but it never mentions the optional `device` parameter at all, leaving its meaning and default entirely undocumented. Only `text` is implicitly covered.

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 (type) and resource (text into the currently focused field on the device), and the focus requirement cleanly separates it from siblings like previewapk_tap_text and previewapk_press_key.

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

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

Gives an explicit precondition — the field must be focused first (tap it) — which implicitly routes the agent to previewapk_tap before calling this. It does not name alternatives or state when not to use it, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does disclose the crucial stateful behavior: the selection persists across all other tools until changed or until a device is started. It does not say what happens if the device name is invalid or whether a confirmation is returned, so it stops short of full behavioral coverage.

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

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

Three short sentences, front-loaded with the core purpose and analogy, then the stateful consequence, then the parameter source. No filler.

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

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

For a one-parameter session-state tool with no annotations or output schema, the description covers purpose, persistence semantics, the competing 'start' path, and where to get the argument. Only failure/validation behavior is left unstated.

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% (the single param is documented as 'device name or id'), so the baseline is 3; the description adds real value by giving the accepted format example ('Device 1') and the authoritative source for the value, previewapk_list_devices.

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 ('Select your working device') and pins down its role with the 'cd of PreviewAPK' analogy, which cleanly separates it from the action siblings (tap, swipe, screenshot) that merely consume the selection.

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

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

Explicitly frames the tool as a prerequisite ('After selecting, every other tool talks to this device'), names the alternatives that also set state ('or start one — starting also selects'), and routes the agent to previewapk_list_devices for valid values.

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

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

With no annotations, the description carries the full burden and does so well: it discloses polling behavior, that timeout returns found=false rather than an error, the return shape {found, waited_ms}, the extra handback_note/resumed fields in driver mode, and the differing timeout defaults (30s for element waits, 300s default / 600 max for driver waits). These are exactly the non-obvious behaviors an agent would otherwise guess wrong.

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?

Dense and front-loaded: the core wait behavior, return contract, and error semantics come before the secondary driver mode. Em-dash heavy phrasing makes a couple of sentences run on, but no sentence is filler.

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

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

For a 7-parameter tool with no annotations and no output schema, the description covers return values, timeout semantics, and the human-handback flow — enough to call it safely. The remaining gap is element-selector semantics and polling cadence, which leaves the most basic invocation slightly under-specified.

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 14%, and the description compensates for three of seven parameters (present, condition, timeout_s) including the important driver-mode timeout override. However, the four element-selector parameters (id, desc, text, device) are never explained — the agent is told to wait for 'an element' without learning how to identify it or which selector takes precedence.

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 with two clearly delineated modes: polling the UI until an element is present (or absent with present=false), and condition='driver' waiting for a human handback. An agent can tell this apart from sibling tools like previewapk_observe or previewapk_screenshot because it is framed as an active wait rather than a snapshot.

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

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

Explicitly says to use it 'after actions that load content instead of sleeping blind', which is a concrete usage trigger, and names the precondition for driver mode ('after previewapk_request_human or any takeover'). It does not name an explicit alternative tool for the same need or state when-not-to-use, so it stops short of a 5.

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