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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds important behavior beyond that: the silent fallback to the embedded bundle, why this matters before a dev-client session, and how app_state can confirm whether Metro is actually in use.

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 purpose is front-loaded and the critical fallback warning is useful context. The long CRITICAL sentence is somewhat verbose, but the overall structure remains clear and each part serves the agent.

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 four-parameter tool with no output schema, it covers purpose, usage timing, failure mode, removal behavior, and the app_state diagnostic path. The input schema covers all parameters, so no critical calling context is missing.

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

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

Schema coverage is 100% and already documents device_port with the 8081/Metro example, host_port defaulting to device_port, serial, and remove. The description reinforces the Metro example and remove=true undo behavior, but adds little meaning beyond the schema.

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

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

It states a specific verb and resource: 'Forward a DEVICE TCP port to a HOST port (adb reverse)' and gives the canonical Metro use. This makes clear it is the port-forwarding tool rather than launch/reload/app_state 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?

It gives explicit timing: set this up before a dev-client session and suspect it whenever edits seem to have no effect. It also says remove=true undoes the forward, though it does not name sibling alternatives or state broader when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true, consistent with a pure reporting tool, and the description adds genuine behavioral context: the stale_verdict is always returned ("never silence") when source_path is given, and it explains the failure mode where a stale Metro on port 8081 makes the app look healthy. That said, it does not disclose cost, latency, or side effects of the probe itself.

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 claim is front-loaded and the escalation to source_path/stale_verdict follows logically; every sentence is doing work. It loses a point for rhetorical padding ("'metro' does not mean the RIGHT metro") and for restating the stale|current|undetermined enum that the schema already declares.

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

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

With no output schema, the description carries the return-value burden and does so by listing the concrete state fields and the stale_verdict outcome with its cause. For a read-only three-parameter diagnostic, nothing an agent needs in order to decide or call is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented, including source_path's mtime-vs-HMR comparison and enum values. The description adds rationale (why source_path matters, what a wrong-Metro checkout looks like) rather than new parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific verb ("Report") and resource ("an app's RUNTIME state") and then enumerates the exact fields returned: installed/running/foreground, top activity, pids, uptime, install/update times, Metro vs embedded bundle, and the dev-server port/pid/root. The emphasis on RUNTIME implicitly separates it from static siblings like get_app_details or list_packages, so an agent can pick it 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 an explicit trigger: "Run this FIRST when JS edits seem to have no effect," plus a conditional workflow (pass source_path to force a stale_verdict). It does not explicitly contrast with sibling diagnostics such as build_status, get_app_details, or reload_app, so the agent must infer those boundaries.

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

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

Annotations already flag destructiveHint=true and openWorldHint=false; the description adds real context beyond that by explaining that load resets the device, i.e. the destruction applies to current device state, and that the tool requires an emulator rather than a physical device. It stops short of stating whether delete is reversible or what happens on a missing snapshot name.

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: purpose and operation list first, then the operational rationale and constraint. No redundant restatement of the title, and 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?

There is no output schema, and the description does not say what the list action returns or what a successful save/load reports, which is a modest gap for an agent verifying results. Everything needed to choose and invoke the tool correctly is present.

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

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

Schema coverage is 100%, so all three parameters and the action enum values are already documented in the schema. The description restates the action values and implies the name argument but adds no format, defaulting, or edge-case meaning (e.g. name collisions on save). Baseline 3 applies when the schema carries the 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?

States a specific verb and resource ("Manage emulator AVD snapshots") and enumerates the exact operations (save|load|delete|list). It also disambiguates from siblings like list_avds, boot_emulator, and shutdown_emulator by scoping to snapshot state and declaring "Emulator-only."

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 concrete workflow rationale — save a known-good state, then load it to reset deterministically between runs — and contrasts it with the wipe_data cold boot alternative. It does not name a sibling tool explicitly, so selection still requires a small inference step, but the when-to-use guidance is clear.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false; the description adds the traits that actually matter: the process is launched detached and outlives the call, it blocks until sys.boot_completed by default, and cold starts take 30-120s. It also discloses the idempotent no-op path and the error semantics for no_snapshot/wipe_data against a live emulator, which usefully qualifies an otherwise understated destructiveHint=false (wipe_data is a factory reset).

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

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

Four sentences, front-loaded with the action and return value, then side effects, then the already-running edge case. Every sentence carries operational information; nothing is redundant with 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?

There is no output schema, but the description states what is returned (the serial) and how to use it. Combined with timing expectations, detached-launch behavior, and the already-running error path, an agent has everything needed to call this correctly on the first try.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and the baseline is 3. The description still adds meaning beyond it: the 30-120s cold-start figure informs how to set timeout_s, and the statement that no_snapshot/wipe_data error when the emulator is already running clarifies interaction rules the schema only partially captures.

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 ("Boot an AVD by name") plus the concrete return value (device serial, e.g. emulator-5554). It also names the related siblings (list_avds for names, shutdown_emulator for stopping), so an agent can distinguish it 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 context (boot a device, then reuse the returned serial for later tools) and an explicit when-not path: if the AVD is already running it returns that serial rather than launching a second one, and no_snapshot/wipe_data error in that case — with the remedy "stop it with shutdown_emulator first."

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?

Goes well beyond the annotations (openWorldHint/destructiveHint), disclosing that the call blocks for the entire build, that failures return the same summary and full-log path as gradle_build, and the newest-non-test APK selection heuristic. These are exactly the operational traits an agent needs before committing to a long blocking call.

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 dense sentences, front-loaded with the action chain, then equivalence, then blocking behavior, then the APK-selection edge case. Every sentence carries non-redundant information.

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

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

With no output schema, the description covers the failure return shape and the blocking/side-effect profile well. The success return value (e.g. what the install/launch summary looks like) is only implied, which is the one remaining gap for a tool whose output the agent must interpret.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, including the assembleDebug default. The description reinforces project_dir and package context but adds no new syntax, format, or constraint information beyond what the schema provides. 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 compound verb chain (build → install → launch) with the exact resource (Gradle task, APK, package) and explicitly names the three sibling tools it replaces. An agent can distinguish it from gradle_build, install_app, and launch_app without opening any schema.

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

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

The 'equivalent to gradle_build + install_app + launch_app in a single call' framing tells the agent this is the one-shot path versus composing three calls. It also resolves the ambiguity of which APK gets installed for multi-flavor projects. It stops short of an explicit when-not (e.g. 'use gradle_build alone if you don't want to install'), which keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered, but the description adds real behavioral value: it enumerates what the terminal summary contains (pass/failed, error count, first errors, APK paths, full-log path) and warns that jobs live only as long as the server process, which tells the agent results can vanish. It does not say what happens when an unknown or expired job_id is 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?

Two compact sentences, front-loaded with the action and immediately followed by the two possible result states. Every clause earns its place by describing either the trigger, the return shape, or the lifetime constraint.

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

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

With no output schema, the description carries the burden of describing returns and does so well by listing both the running state and the final summary fields. The only meaningful omission is error behavior for an invalid or expired job_id, which matters given the stated process-lifetime limitation.

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 a single parameter with 100% schema description coverage, and the schema already says job_id comes from gradle_build with background=true. The description repeats that origin rather than adding format, validation, or expiry semantics, so the baseline of 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 and resource ("Report a background gradle_build") and explicitly scopes it to builds started with background=true, which cleanly separates it from the sibling gradle_build. An agent can distinguish this polling tool from the build-launching tool 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?

The parenthetical "(started with background=true)" makes the trigger condition clear: use this after launching a backgrounded gradle_build. It stops short of stating the negative case (that foreground builds need no status call, or that repeated polling is expected), so it is clear context rather than full when/when-not 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 idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds valuable non-annotation context: the capability is emulator-only, omitted fields are left unchanged (partial-update semantics), and changes are aimed at deterministic test scenarios. It does not explain how to reset the radio afterwards, which would be the last piece of 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?

Purpose and the two main parameter groups are front-loaded, and the trailing sentences carry the testing rationale and the emulator-only constraint. It is dense with parenthetical detail (enum lists, example profile names) that partially duplicates the schema, which keeps it just below a 5.

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 emulator-state mutation with full schema coverage and annotations, the description supplies the essential extras: emulator-only scope, partial-update behavior and intended test use. With no output schema, it would benefit from a line on what confirmation or resulting state the caller sees, and on resetting the radio.

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

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

Schema coverage is 100%, so the per-parameter documentation baseline is 3. The description still adds meaning beyond the schema by stating the cross-field rule that all fields are optional yet at least one must be set, and by explaining that unset fields remain unchanged, which the schema only implies per-property.

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

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

The description opens with a specific verb and resource ('Shape the emulated cellular radio') and names the underlying mechanisms (adb emu gsm / network), then enumerates the exact controllable facets: registration state, signal strength, throughput and latency. It is clearly distinguishable from siblings such as phone_call, send_sms, set_battery or set_sensor, which touch different device state.

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

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

It gives a concrete usage context ('Test offline/roaming/weak-signal and slow-network behaviour deterministically') and a hard precondition ('Emulator-only'), plus the operational rule 'Every field optional; set at least one'. It stops short of naming alternatives for adjacent device-state tools or stating how to restore defaults, so it is strong but not exhaustive.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the bar is lower; the description still adds real value by stating exactly what is erased (data and cache) and what state the app lands in (first launch). It stops short of noting that login state, permissions, and local databases are irrecoverably lost, which is the main risk an agent should consider.

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, front-loaded with the action and mechanism, followed by the outcome and the use case. No redundant restatement of the title and nothing 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 simple two-parameter destructive tool with full schema coverage and no output schema, the description covers action, mechanism, and result state adequately. Only the loss of authentication/onboarding-adjacent state is left implicit, a minor gap given the destructiveHint annotation.

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% — both parameters, including the optional serial fallback behavior, are documented in the schema itself. The description adds no parameter-level meaning beyond that, 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 gives a specific verb+resource ('Wipe an app's data and cache'), the underlying mechanism (pm clear), and the resulting state ('first-launch state'). This clearly separates it from siblings like stop_app, reload_app, and uninstall_app, which do not remove stored data.

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 provides a concrete usage context: reproducing onboarding/permission flows from scratch. However, it never names an alternative or exclusion — e.g. that uninstall_app or revoke_permission are different choices when you want to remove the app or just drop a grant — so the agent must infer when this is preferable.

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

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

The annotations already declare destructiveHint=true and openWorldHint=false, and the description is consistent with them by framing this as a removal. It adds that a credential is required and that the operation is meant for post-test cleanup, but it does not say whether the lock can be re-set afterward, what happens on an incorrect credential, or whether any device state is lost — meaningful gaps for a destructive 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 short sentences with the action stated first and the usage hint second — no filler. The phrase about old_value partially restates the schema description, which is the only real 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?

For a two-parameter, no-output-schema tool this is close to adequate: the action, the required credential, and the intent are all present. What is missing is the precondition (a lock must currently be set) and the consequence of failure, which matters because annotations flag the call as destructive.

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 old_value are already documented in the input schema. The description reinforces old_value as 'the current credential' but adds no syntax, format, or failure semantics beyond what the schema states, so the baseline of 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 gives a specific verb and resource: 'Remove the secure lock screen', which an agent can map directly to a state change on the device. It never names the adjacent sibling set_device_lock (which sets the same lock) or is_device_secure, so the agent must infer the distinction from names 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?

'Use to restore a clean state after testing a Keystore flow' supplies one concrete scenario, but it is narrow and reads as a recommendation rather than a rule. There is no statement about when not to call it (e.g. device already unlocked, no lock configured) or that set_device_lock is the counterpart for enabling a lock.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the description's job is to say what is destroyed and why it matters; it does that well by explaining that prior log lines become unreachable and that an empty read may otherwise be misread as buffer rotation. It stops short of stating failure modes (no device attached, permission problems) or whether clearing is device-wide across all apps, which would be the remaining useful behavioral detail.

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 adb equivalent, then the rationale, then the alternative — a sensible order with no filler sentences. Minor deduction for editorial framing ('The sharpest isolation primitive') that costs tokens without adding selection 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 one-parameter, no-output-schema utility, the definition covers effect, workflow role, and the competing option, which is enough to call it correctly. The only gap is scope detail an agent might want (device-wide vs per-app, behavior with zero attached devices).

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 documented there, including the 'optional when exactly one device is attached' rule. The description adds no further meaning about the parameter, 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 and resource ('Empty the device's logcat ring buffer') plus the underlying adb command, which disambiguates it from the sibling `logcat` (read) and `start_logcat_capture`/`stop_logcat_capture` (capture lifecycle). An agent can pick this tool 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 an explicit when-to-use pattern — clear, perform ONE action, then read logcat — and names the alternative for the opposite need ('For reaching BACK in time instead, use logcat's since param'). It also explains why the alternative matters (stale filter hits, rotated buffers), so the routing decision is unambiguous.

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 openWorldHint=true and destructiveHint=false, so the bar is lower, and the description adds real context: pairing is a distinct prerequisite step that must happen before connecting and requires a code displayed on the device. It does not mention failure behavior (timeouts, unauthorized keys), 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?

Two sentences, front-loaded with the core action and followed by the pairing condition and argument guidance. Every clause carries information an agent needs, with no filler.

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

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

For a three-parameter, no-output-schema connection tool whose annotations already convey the safety profile, the description covers the necessary inputs and the pairing prerequisite. Only edge-case behavior on failed connections 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%, so each parameter is already documented, and the description largely restates schema content such as pair_address differing from host_port and pairing_code enabling pairing. It adds only the framing that host_port is the primary argument and pairing args are conditional, which matches the baseline for a fully documented schema.

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

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

The description names a specific verb and resource ('Connect to a device over Wi-Fi/TCP') and names the underlying mechanism (adb connect / adb pair), so an agent can tell exactly what the tool does and how it differs from device-listing or app-launching 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?

It states the required host:port input and the condition under which pairing extra arguments apply ('Android 11+ Wireless debugging' with a 6-digit code), which is clear context for use. It stops short of explicit exclusions such as when to prefer a USB/emulator connection path over this 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?

Beyond the readOnly/openWorld annotations, it discloses focused-window and system-overlay behavior, hidden-node counts, filter semantics, viewport-scoped accessibility-tree omissions, and the absence of canvas-drawn content in every mode. These are substantial behavioral details an agent needs to avoid incorrect conclusions.

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

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

The description is dense but front-loaded: it starts with what is returned and the aiming use case, then covers caveats and alternatives. Every sentence contributes operational guidance, with no filler.

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

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

For a read-only UI inspection tool with no output schema, the description supplies the critical return semantics, coordinate behavior, focus-window caveats, filter tradeoffs, and scope limitations. An agent has enough context to invoke it correctly and interpret its results.

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

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

Schema description coverage is 100%, and the schema already documents query matching, filter modes, serial targeting, compact output, and package focus expectations. The description reinforces strategy around filter and query use, but adds limited meaning beyond what the schema already provides.

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

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

It states a specific operation: read the on-screen UI hierarchy as elements with text, content_desc, resource_id, class, clickable flag, bounds, and true-device-pixel centers. It also clearly distinguishes the tool from screenshot-based guessing and from render_stats for counting.

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

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

The description gives explicit when-to-use guidance: pass an element's center directly to tap, never infer coordinates from a downscaled screenshot, scroll before concluding absence, and use render_stats instead for long-list counting. It also explains when to use query, clickable filtering, and all-mode filtering.

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

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

The annotations already establish this as a safe, non-destructive, local-only read (readOnlyHint=true, openWorldHint=false), so the description only needs to add context — and it does, explaining the diagnostic dependencies (Gradle needs a JDK; system gradle is required only so scaffold_android_project can generate a wrapper). It does not describe the shape or grouping of the report, but the safety profile is fully covered by annotations.

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

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

Content is front-loaded with the verb and resource, and the second sentence carries the trigger condition, so the structure is sound. The first sentence is long and stacks several parenthetical asides, which makes it slightly harder to scan than an ideal definition, but no clause 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?

There is no output schema, so the description carries the burden of telling the agent what it will learn — and it enumerates the checks in enough detail to know what a result will contain. Combined with the trigger guidance, an agent has everything needed to decide to call it and interpret the outcome.

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, which is the correct baseline-4 case; there is nothing for the description to disambiguate. The absence of arguments is itself consistent with the "run it and it checks everything" framing.

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?

"Diagnose the local toolchain" is a specific verb plus resource, and the description then enumerates exactly what is probed (SDK path validity, adb/emulator availability, AVDs, attached devices, per-device accessibility bridge status, JDK, system gradle). This clearly separates it from narrower siblings such as list_devices or list_avds, which each cover only one slice of the same surface.

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?

"Run this first when something isn't working" plus the concrete trigger (a Gradle tool failing with "SDK location not found") gives an agent a clear, actionable entry condition, and "first call of any session that isn't going well" further scopes it. What is missing is any when-not guidance or explicit hand-off to siblings once the diagnosis narrows the problem.

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=false and openWorldHint=false, so the safety profile is known. The description adds genuinely new behavioral context: the gesture holds at the start before moving, and the tool requires Android 11+ (input draganddrop) — a hard platform constraint an agent must know before calling. It stops short of describing failure modes or what happens on unsupported API levels.

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 tightly packed sentences with zero filler; the coordinate/gesture definition is front-loaded and the disambiguation against swipe follows immediately, matching the order an agent needs to evaluate the 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?

For a simple coordinate-input tool with a fully documented schema, annotations, and no output schema, the description covers purpose, gesture mechanics, and the Android 11+ prerequisite. The only real gap is a brief note on duration tuning for slow reorder interactions, which is minor.

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

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

Schema description coverage is 100%, so all six parameters including duration_ms and the optional serial are already documented. The description restates the 'true device pixels' unit but adds no syntax, defaults, or tuning guidance (e.g. when to raise duration_ms for reorder lists) beyond the schema, so 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 sequence and resource: 'Press-hold-move-release drag from (x1,y1) to (x2,y2) in true device pixels', plus the underlying primitive (input draganddrop, Android 11+). It explicitly distinguishes itself from the swipe sibling, so an agent can pick between drag, swipe, and long_press without opening schemas.

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

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

Gives concrete when-to-use cases (drag handles, long-press-to-reorder lists, drag-and-drop targets) and names the contrasting sibling ('Unlike swipe (which flings)'). It does not address the long_press sibling, which overlaps with the hold-at-start behavior, leaving one routing decision 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 only declare openWorldHint=false and destructiveHint=false, so the description carries most of the behavioral burden and does well: it discloses the settle delay between taps, the pad-specific visibility constraint, the precedence rule that coords overrides grid and hierarchy, and where to obtain bounds (a screenshot). The gap is risk disclosure — entering a PIN can trigger device lockout or biometric fallback, and neither that consequence nor any verification of successful entry is mentioned.

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 the input_text failure case before the pad-taxonomy detail, and the em-dash/caps structure makes the native-vs-canvas branch scannable. It runs long and duplicates some of the grid/coords explanation already in the schema, so a little tightening is possible, 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 4-parameter input-simulation tool with no output schema and thin annotations, the definition covers the hard part — deciding which targeting mode to use and what prerequisite UI inspection to run. It stops short of stating the outcome of the call (does it confirm entry, what happens on timeout or wrong pad detection) or the lockout risk, which matters for a PIN-entry tool with siblings like is_device_secure, set_device_lock, and prefer_pin.

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

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

Schema description coverage is 100%, so the schema already defines grid, coords, digits, and serial in comparable detail; the description largely restates the grid/coords distinction. It adds modest value by framing grid as 'the pad's bounding box' on a 'standard 3x4 dialpad' and telling the agent to read bounds off a screenshot, which is procedural meaning beyond the schema's types.

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 ('Enter digits on a numeric PIN pad by tapping each key') and immediately distinguishes itself from the sibling input_text, naming the exact condition where input_text fails. An agent can select this tool over input_text, press_key, or tap 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?

Explicit when-to-use ('when input_text does nothing because the pad renders its own key views'), an explicit prerequisite ('run describe_ui on the pad screen first'), and a decision rule for which argument to supply: default hierarchy for native-view pads, 'grid' or 'coords' only for canvas-drawn React Native / Skia pads. Alternatives and exclusions are both present.

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

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

Goes well beyond the annotations (which only say openWorldHint=false, destructiveHint=false) by disclosing a false-success failure mode ('reports OK even when the id matches nothing'), the HAL lockout risk from sweeping ids, and the hang when nothing is enrolled. It also names the environment restriction (emulator-only) and points to a guide resource for the enrollment workflow.

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 what the tool does, then prerequisites, then gotchas, in a sensible order. Dense but nearly every sentence carries operational weight; the trailing guide/skill parenthetical and repeated emulator-only framing add slight 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?

For a two-optional-parameter tool with no output schema, the description covers everything an agent needs: scope (emulator), preconditions (enrollment check), argument correctness (id must match enrolled finger), and return-value caveats (OK is not proof of success). Nothing material is missing.

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

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

Schema coverage is already 100%, so both serial and finger_id are documented in the schema itself. The description reinforces the key constraint that finger_id must match an enrolled finger (default 1) and warns against sweeping ids, but adds no new detail about serial.

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 concrete verb and resource ('Simulate a fingerprint-sensor touch on an EMULATOR') and even names the underlying command 'adb emu finger touch'. It is clearly distinguishable from siblings like finger_remove, has_biometric_enrolled, enter_pin, and prefer_pin, which it implicitly contrasts with via the PIN-fallback sentence.

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 (to drive the real BiometricPrompt path rather than cancelling into PIN fallback) and a hard prerequisite ordering: 'Check has_biometric_enrolled FIRST'. Also states the emulator-only scope, which rules out physical devices.

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 idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new operational context: this only works against emulators and it exists to emit a finger-up event. It does not state what happens if no finger is currently down, though the idempotent hint largely covers that.

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 the action first, the raw adb equivalent parenthetically, and the emulator constraint at the end. No redundant restatement of the title or 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?

For a trivial one-call emulator control with full annotation coverage and no output schema, the description says everything an agent needs to decide and invoke. Only a note about the expected response or no-op behavior 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?

With a single optional parameter at 100% schema description coverage, the schema already explains the serial/-s targeting and the single-device default. The description adds no meaning beyond that, which is the expected baseline.

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

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

States a specific verb and resource ("Lift the simulated finger off the sensor"), grounds it in the underlying command (adb emu finger remove), and explicitly positions it as the complement to fingerprint_touch. An agent can distinguish it from the sibling that presses the finger down without opening either schema.

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

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

Gives concrete applicability ("for flows that watch for the finger-up event") and a hard scope limit ("Emulator-only"), plus names the sibling it pairs with. It stops short of an explicit when-not rule, e.g. what to do on a physical device where this call is meaningless.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description is consistent with a pure read. It adds real value beyond annotations by disclosing the underlying commands, that apk_path mode requires no attached device (aapt2), and what is returned in each mode. It stops short of stating behavior when the package is not installed or the apk path is invalid.

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 primary outcome (version + launchable activity) before the alternate mode. Parenthetical implementation details are dense but each reinforces a distinct fact; no filler text.

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

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

For a 3-parameter, read-only tool with annotations and no output schema, the description supplies what an agent needs: what is returned in both modes, when the device is unnecessary, and the fallback if no device is attached via the optional serial.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds mode-selection semantics: apk_path substitutes for package and switches to an offline aapt2 read that yields package id, version and launcher activity. The mutual-exclusivity relationship between package and apk_path is reinforced beyond the schema wording.

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: reports an installed app's version name/code plus its launchable activity. It names the underlying mechanisms (dumpsys package + resolve-activity) and clearly separates the two modes (device query vs. local .apk read), which distinguishes it from siblings like list_packages or app_state.

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

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

Gives explicit when-to-use framing: 'to confirm what build is installed and find the activity to launch', plus a stated condition for the alternate mode ('pass apk_path instead of package... no device attached — handy right after gradle_build'). It does not name sibling tools it replaces or should be preferred over, so routing against list_packages/app_state 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 only cover openWorldHint and destructiveHint=false; the description adds that a real Gradle task is executed, that multi-module reports are merged, that JVM unit tests are the only supported scope, and how to switch output format. It does not mention execution time, failure behavior, or that the build is compiled as a side effect, 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 output, then the caveat and alternatives in descending priority. Slightly dense in the middle clause and repeats a few schema facts, but no sentence 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?

No output schema exists, and the description explains what the summary contains plus the JSON alternative, and it covers the main failure mode (missing JaCoCo task on Android projects). Missing only runtime/failure-handling details for a build-executing 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% and the description largely restates schema content (json=true, task default, project_dir). It does add the module-qualified name convention and the AGP fallback rationale, but these are already in the task parameter's own 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?

Specific verb+resource: 'Run a JaCoCo coverage-report Gradle task ... and summarize coverage' with the exact output contents (line/branch/method/class percentages, per-package breakdown worst-first, merged multi-module). It is clearly distinct from siblings like get_file_coverage and run_unit_tests.

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

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

Explicitly scopes usage ('JVM unit tests only'), states the default task, names the AGP alternative task to pass when the default is absent, and routes the agent to list_gradle_tasks plus a skill/resource for discovering it. Alternatives and exclusions are both present.

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

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

With only openWorldHint/destructiveHint supplied, the description carries most of the burden and does so well: suffix matching semantics, ambiguous-name behavior (returns every match), and miss behavior (lists files that have data) are all disclosed. The remaining gap is cost — it implies a Gradle/JaCoCo run happens but never says whether calling it triggers a build or reuses a prior report.

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 scope and relation to get_coverage_report, then behavior caveats, then the JSON flag. Every sentence carries information, though the task-fallback aside is dense enough that it reads closer to schema prose than invocation guidance.

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

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

No output schema exists, and the description compensates by naming the return content (line-level and per-method detail) and offering the json=true alternative shape. The only omission is whether coverage data is freshly generated or read from an existing report, which matters for a tool that shells out to Gradle.

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

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

Schema coverage is 100%, so all five parameters including the task fallback and project_dir defaults are already documented in the schema. The description only restates file suffix matching and json=true, adding no new syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific resource (JaCoCo coverage for one source file) and the exact payload: missed and partially-covered line numbers plus per-method detail. It explicitly positions itself against the sibling get_coverage_report by scope, so an agent can distinguish the two 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 an explicit workflow ordering: 'Use it after get_coverage_report names the weakest package.' It also states a hard applicability boundary ('JVM unit tests only'), which tells the agent when not to reach for it, and points at list_gradle_tasks as the fix path when the default task is absent.

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

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

The annotations only flag openWorldHint and destructiveHint; the description adds real context beyond them — host-vs-device execution, credential-shaped value redaction in the log, and the caveat that the APK list can include artifacts from earlier builds. It could still say what a build overwrites in build/outputs to earn the destructive flag more concretely.

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 action and location before the return-value and background details. Minor overlap with the schema on project_dir and background, but 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?

With no output schema, the description carries the return contract itself: status, duration, error count, first errors, full-log path, and a newest-first APK listing. Combined with the async job-id path, 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 100%, and each schema property already documents task default, extra args, background polling, and the session-default fallback for project_dir. The description restates those same points rather than 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?

"Build the app with Gradle (default task assembleDebug) in project_dir" gives a specific verb, resource, and default. "Runs on the host, not a device" partially separates it from device-side siblings, but the most confusable neighbor, build_and_run, is never named or contrasted.

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 conditions are clear: project_dir must contain the wrapper (or be pinned via session_set_defaults), and background=true is prescribed for multi-minute builds with build_status for polling. It stops short of saying when to choose this over build_and_run or run_unit_tests.

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 only readOnlyHint and openWorldHint; the description adds materially: the output equals what './gradlew properties' prints, may surface credentials read from ~/.gradle/gradle.properties or env (private Maven repo auth), and secret-shaped keys (password/token/key/credential) are redacted before return. That is exactly the security and scope context an agent can't infer from the annotations, and it does not contradict readOnlyHint.

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 it does, then routing, then the safety caveat last where it matters most. Every sentence carries load, including the credential/redaction warning, with no restating of the title or annotations.

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 names the kind of content returned (namespace, SDK settings, build directory, full effective property set), its parity with ./gradlew properties, and the redaction behavior. That is sufficient for a two-parameter read-only tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in-schema, and the module example in the description duplicates the schema text. The description never mentions project_dir or the session default fallback, so it adds essentially no parameter meaning beyond structured fields; 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 ('Dump') and resource ('Gradle's evaluated properties') scoped to one module, with concrete module-path examples (:app, :feature:login). It also implicitly separates this from list_gradle_projects, list_gradle_tasks and list_gradle_variants by contrasting 'effective configuration' with 'just its task/variant names'.

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 names the sequencing ('Use after list_gradle_projects') and the deciding condition: you need namespace, Android SDK settings, build directory or other effective configuration rather than task/variant names. An agent can pick between this and the sibling list_* tools without opening a schema.

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 idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact: the operation changes app permission state silently, bypassing the in-app dialog. It omits prerequisites such as the permission needing to be declared in the manifest, the runtime-permission API level requirement, or whether the app must be restarted to observe the change.

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: verb+resource first, then mechanism, then the practical benefit. No filler and no repetition of schema content.

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

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

For a three-parameter mutation tool with no output schema, the description covers what it does and why but leaves out call-affecting prerequisites (manifest declaration, API level, whether the app must be installed/running) and the fact that the change is undone via revoke_permission. 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 100%, so package, permission and serial are already documented in the schema, including the same android.permission.CAMERA example. The description adds no meaning beyond that, which is the baseline 3 case.

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 ("Grant a runtime permission to an app") plus the concrete mechanism ("pm grant") and an example permission value. The grant/revoke distinction against the sibling revoke_permission is implicit in the verb but the sibling is never named, so this falls just short of full sibling differentiation.

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 clause "skips the in-app permission dialog so you can drive straight to the feature" tells the agent exactly why and when to reach for this tool instead of driving the permission UI with tap/tap_on_text. It stops short of explicit exclusions (e.g. non-runtime permissions, or when to prefer revoke_permission to undo the change).

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 and openWorldHint=false, but the description adds real context: it reads dumpsys, only a count is exposed, it works on emulators and physical devices, and wrong finger ids risk a HAL lockout. That lockout warning is operationally important and appears nowhere in the structured fields.

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 purpose, then prerequisites, then caveats. It is dense but every sentence carries a distinct constraint; the final sentence is slightly long but still earns its place via the lockout warning.

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

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

With no output schema, the description correctly states the return content (whether enrolled and how many). It also covers device scope and the main failure mode, leaving nothing an agent needs before calling 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 100% and the single optional serial parameter is fully documented there. The description adds no meaning about the serial argument, so the baseline of 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 and resource ('Report whether any fingerprint is enrolled (and how many)') and names the data source (dumpsys fingerprint). It is clearly distinguishable from siblings like fingerprint_touch and finger_remove.

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 'Check this BEFORE a biometric flow' and explains the consequence of skipping it (fingerprint_touch sits on 'Touch the sensor'), then routes the agent to enrolling or the PIN path. Both the when and the alternative branches are spelled out.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false, so the description must contribute the operative constraints – and it does, with the Android 11+ requirement and the modifier-first ordering rule that governs how chords are interpreted. It stops short of stating failure behavior (e.g. unsupported key names, missing device) or what the response 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?

Front-loads the core action and packs the routing rule into the same sentence. The preset list and examples are repeated from the schema, which is mild redundancy but keeps the description self-sufficient.

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 zero-required-parameter input tool with no output schema, this covers action, format, version constraint, and the sibling alternative. The only real omission is device-targeting behavior for serial when multiple devices are attached.

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 keys, preset, and serial are already fully documented including the modifier-first example and the at-least-2 rule. The description restates the same ordering and preset list, adding little beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb and resource ("Press several keys together as a chord") and immediately distinguishes itself from the sibling press_key for single keys and implicitly from input_text. The Android 11+ platform note scopes it further.

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: use preset for named shortcuts, keys when spelling out a chord, and press_key instead for a single key. This is a clear when-to-use / when-not-to-use / alternative triple.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false, so the description carries most of the burden — and it does, disclosing the visible side effect (soft keyboard covering lower buttons) and the silent-no-op failure mode on non-IME PIN pads. It stops short of stating whether existing field content is replaced or appended, and whether a failure is reported, 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 tight sentences: action first, then the focus prerequisite, then the side-effect workaround and the alternative tool. No filler and no repetition of schema details.

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, non-destructive input tool with no output schema, the definition covers the prerequisite, the side effect, the mute failure case, and the sibling to use instead. The main remaining gap is append-vs-replace behavior on a field that already has content.

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

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

Schema coverage is 100% and both parameters (text, serial) are already documented, so the baseline applies. The description only mildly enriches "text" by tying it to the focused field; it adds no format, length, or escaping guidance.

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 ("Type text into the currently focused input field via the IME") plus the mechanism (IME), which distinguishes it from press_key, input_key_combo, and enter_pin without needing 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 an explicit prerequisite ("Tap the field first so it has focus"), a named exclusion (native non-IME PIN pads), and the alternative to use instead (enter_pin). It even prescribes the follow-up action (dismiss keyboard with press_key escape/back) before tapping lower buttons.

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 idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavior (the -r reinstall flag), but says nothing about blocking duration, failure modes such as signature/version conflicts, or what a successful result 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?

Two short sentences with the action front-loaded and no filler. The parenthetical '-r' is compact but slightly cryptic without stating what reinstall implies for existing app data.

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

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

For a simple two-parameter tool with full schema coverage and annotations, this is nearly complete. The remaining gap is that with no output schema, the description does not indicate whether the call blocks until install finishes or what success/failure feedback is returned.

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

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

Schema coverage is 100%, so both parameters are already documented. The description reinforces that apk_path is a local filesystem path and introduces the -r reinstall semantics, but adds no detail on serial/device selection or path formats beyond the schema.

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

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

States a specific verb+resource (install an APK from a local file path onto the device) and names the reinstall variant. It is clearly distinct from siblings like uninstall_app or launch_app, though it does not explicitly contrast with reload_app/launch_app for the post-install step.

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 to deploy a build you want to test' gives an implied usage context but no explicit when-not or alternatives (e.g., use launch_app after installing, use gradle_build to produce the APK). Device-targeting guidance lives only in the schema, not the description.

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 and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the implementation (locksettings probe) and what the answer semantically reflects (the signal Keystore checks), but it never says what the call actually returns, so an agent cannot tell whether to expect a boolean, a string, or a structured object without a separate output schema.

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

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

Two sentences, front-loaded with the purpose before the usage cue. The nested parenthetical audit trail is slightly heavy but every clause is informative and nothing is padding.

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

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

For a one-optional-parameter read-only probe with no output schema, the definition covers what is checked, why it matters, and the verification workflow. The only material omission is the shape of the returned result, which an agent must discover at call time.

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% — the single optional serial parameter is fully documented with the multi-device fallback. The description adds nothing about the parameter, which is acceptable given the schema carries it.

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 check — whether a secure lock screen is set — and pins down its semantics by naming the underlying probe (locksettings) and the equivalent API (KeyguardManager.isDeviceSecure, which Keystore gates on). That goes well beyond the tautological title. It does not explicitly name the near-neighbour checks it is not (has_biometric_enrolled, clear_device_lock), so it stops short of a full 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?

"Use it to verify set_device_lock worked before running a Keystore-gated flow" gives an explicit when-to-use and names the sibling that precedes it. No when-not guidance or alternatives for adjacent security checks, but the intended context is unambiguous.

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 and openWorldHint=false, so the description's added value is the source and retention semantics of DropBox versus the logcat ring buffer — genuinely useful context an agent cannot infer from the annotations. It does not cover edge cases such as behavior when no crash is present, which keeps it at a 4.

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 what the tool returns, followed by the disambiguation advice. Every clause carries information; nothing is padding.

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

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

For a two-parameter read tool with no output schema, the description covers the source, scope, filtering and return contents adequately. It stops short of saying what comes back when no crash exists, which is the one operational detail an agent might still need.

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; the description's 'Optionally filter to a package' merely restates the package parameter. It adds no format or semantics 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?

States a specific verb and resource ('Return the most recent app crash from the system DropBox') plus the exact data source (dumpsys dropbox) and payload shape (exception header + stack in one call). It is clearly distinguishable from the sibling 'logcat' tool, which it explicitly contrasts.

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 routing rule: 'Use this instead of grepping logcat when an app just crashed,' and explains the condition that makes it preferable (DropBox retains the full fatal even after it scrolls out of the logcat ring buffer). The alternative and the selecting condition are both named.

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

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

Annotations already declare non-destructive and non-open-world, so the safety profile is covered; the description adds what the agent actually needs beyond that — the LAUNCHER-activity targeting, that the resolved component is echoed on success, and that failure produces a clear message rather than a raw monkey dump.

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 action and mechanism, then failure behavior, then the sibling pairing. The parenthetical "(not a raw monkey dump)" is a slightly incidental implementation aside but still communicates error quality, so it 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?

There is no output schema, so the description usefully states what success returns (the resolved component) and what failure looks like. Device targeting is covered by the schema. Only the relationship to restart-adjacent siblings remains unaddressed, which is minor for a simple two-parameter action.

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 `package` and `serial` are already documented, including the single-device default for `serial`. The description reinforces that `package` is a package name but adds no format or resolution detail beyond the schema, so the baseline of 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 and resource ("Launch an app by package name") and immediately explains the mechanism — starting the package's LAUNCHER activity — which separates it from siblings like install_app, reload_app, and app_state without needing to name 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?

Gives an explicit combination pattern: pair with stop_app to restart from a known state. It does not explicitly exclude or contrast with reload_app or launch_dev_client, which are the closest ambiguous alternatives, so routing guidance is strong but not complete.

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

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

Annotations only cover title, openWorldHint=false and destructiveHint=false, so the description must carry the behavioral load — and it does: it discloses the deep-link construction, the localhost:8081 defaults, the adb_reverse prerequisite, and the specific failure mode if the prerequisite is skipped (falls back to the embedded bundle). That fallback consequence is exactly the kind of non-obvious behavior an agent needs before invoking.

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 action and its mechanism come first, prerequisites second, and the sibling alternative last — a logical order with no filler sentences. Quoted deep-link template and the `{device_port: 8081}` invocation are dense, high-value content rather than padding.

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

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

With no output schema and a simple open-a-deep-link action, the description covers everything needed: what gets opened, what the caller must set up beforehand, what happens if they don't, and where to go for the Expo Go case. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including defaults and the device-serial semantics; the baseline here is 3. The description mostly restates scheme/host/port rather than adding new constraints (e.g. whether serial is required when multiple devices are attached is only implied by the schema's own wording).

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 ('Launch an Expo dev build straight at a Metro dev server') and explains the concrete mechanism (building and opening a `<scheme>://expo-development-client/?url=...` deep link). It is clearly distinguished from nearby siblings launch_app and open_url, the latter of which is explicitly named as the wrong tool for dev builds.

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 (dev build + Metro), an explicit prerequisite ('run adb_reverse {device_port: 8081} first'), and an explicit alternative for the other case ('For plain Expo Go ... use open_url with the exp:// URL instead'). An agent can route correctly without consulting any other tool.

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 and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: only bootable AVDs are returned (a filtering guarantee) and the output is a set of names usable as boot_emulator input. It does not mention cost, latency, or behavior when no AVDs are installed.

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, no filler, and the identification of the resource comes first followed by the workflow placement. Every clause earns its place by either defining the resource or routing the agent.

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 zero-parameter read tool with no output schema, the agent knows what it gets (bootable AVD names) and what to do next (boot_emulator). The only gap is the empty-result case, which an agent can handle reasonably without further text.

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 schema is already closed with additionalProperties=false. Baseline applies and the description does not muddy it with phantom 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?

States a specific verb and resource — 'List the Android Virtual Devices (AVDs)' — and narrows the scope to those 'installed on this machine that can be booted'. That qualifier separates it from the sibling list_devices, which covers connected/running devices, so an agent can pick correctly without opening either schema.

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

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

Gives an explicit trigger — 'Start here when no emulator is running yet' — and names the downstream consumer, boot_emulator, which the returned names feed. It lacks an explicit 'do not use when…' clause pointing at list_devices for already-running emulators, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so safety is covered. The description adds real value beyond them by decoding the returned adb states ('device = ready, offline, unauthorized') and by flagging the rn-expo ordering pitfall (adb_reverse before launch, app_state before trusting results). It does not describe the full return shape, but for a read-only listing that gap is modest.

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

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

The core purpose and usage are front-loaded in the first two clauses. The rn-expo sentence is longer than needed with nested parentheticals and reads partly like a pointer to other documentation, which dilutes the listing tool's own description, though it is not wasted given the stated ordering pitfalls.

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-optional-parameter read tool with annotations covering safety and no output schema, the description supplies the state vocabulary and pre-launch verification guidance an agent needs. Only minor gaps remain, such as whether model/API level are also returned.

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

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

Schema coverage is 100% and the serial parameter is already documented as optional when one device is attached. The description's 'get the serial when several are attached' reinforces the same idea rather than adding new semantics, so the schema is doing the heavy lifting.

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

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

States a specific verb and resource ('List attached emulators/devices') and adds the scope detail that separates it from siblings: it reports attached devices with their adb state, not available AVDs (list_avds) or boot readiness (wait_for_boot). The parenthetical 'device = ready, offline, unauthorized' pins down exactly what is reported.

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 two concrete selection cases: confirm a device is up before driving it, and fetch the serial when multiple devices are attached. It also routes the agent to the rn-expo guide for ordering constraints. It stops short of naming exclusion alternatives explicitly (e.g., use list_avds to create an AVD, wait_for_boot to block on boot), so it is strong but not fully routing-complete.

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 and openWorldHint, so the safety profile is covered; the description adds real behavior context by noting it shells out to the Gradle wrapper and that single-module builds report no sub-projects. It stops short of mentioning execution cost/timeouts or failure modes when the wrapper is missing.

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, purpose front-loaded, with the sibling routing and the task-path syntax following in priority order. No filler or repetition of the title.

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-optional-parameter read tool with no output schema, the description supplies the return shape (a module map with examples) and the edge case of a single-module build. Minor gap: nothing on behavior when project_dir is unresolved or gradlew is absent.

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 schema already explains project_dir, including the session_set_defaults fallback. The description only implies the path is where gradlew runs, adding little beyond the schema, so the baseline of 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?

Names a specific verb and resource (list Gradle modules/sub-projects) and grounds it in the underlying command (gradlew projects). It explicitly differentiates from sibling tools gradle_build and list_gradle_variants, so the agent can select it 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?

States concrete follow-on use cases: find the module to pass to gradle_build/list_gradle_variants, or address a task with '<path>:<task>' syntax. The alternative tools are named and the condition that selects them is spelled out.

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 and openWorldHint=true, so safety and network-awareness are covered. The description adds real behavioral context beyond that: in a multi-module build only the ROOT project's own tasks appear by default, which is a non-obvious output-scoping behavior an agent would otherwise get wrong. It stops short of noting runtime cost or wrapper prerequisites.

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 primary purpose first and the multi-module caveat as a follow-on clause. The parenthetical invocation and inline example are compact enough to earn their 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?

A simple two-optional-parameter read tool with annotations and no output schema, and the description covers purpose, scoping behavior, and module discovery. Only minor omissions remain, such as whether the output is verbatim gradlew text or parsed, which matters for parsing the result.

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 parameters are already fully documented, including the ":app:tasks" example and the session_set_defaults fallback for project_dir. The description largely restates that, adding only the cross-reference to list_gradle_projects as the source of module names, so the baseline of 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 and resource ('List the available Gradle tasks') and grounds it in the concrete invocation ('gradlew tasks'), then adds the intent ('to discover build/test/install targets'). This distinguishes it from list_gradle_projects and list_gradle_variants without the agent needing to open 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 a clear use case (discovering build/test/install targets) and specifies the multi-module default plus the exact condition to override it with task="<module>:tasks", including where to get the module name (list_gradle_projects). No explicit statement of when-not-to-use or why to pick list_gradle_variants instead, 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?

Beyond readOnlyHint/openWorldHint the description discloses real behavioural details: test-only APK tasks (androidTest/unitTest) are excluded from results, and the root project of a multi-module build typically yields nothing. It does not mention that the call shells out to the Gradle wrapper and is therefore slow, which would be the remaining useful trait.

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 free of filler; each sentence carries new information (mapping, exclusions, multi-module caveat). It is dense to the point of being slightly long, packing three distinct ideas into a single sentence, but 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?

No output schema exists, and the description compensates by implying the result is variant names reusable as the task= argument. Together with the exclusion rules and the multi-module workaround, an agent has enough to call it correctly; only the return shape (plain name list vs. structured entries) is left implicit.

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 3 is the baseline, but the description adds genuine meaning: it explains the variant-name-to-task mapping (V -> assembleV/installV) and shows a concrete scoping form task=":app:tasks" along with where that module name comes from.

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

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

States a specific verb (list) and resource (buildable build variants in project_dir) and explains the underlying derivation (parsed from assemble* tasks). It also distinguishes itself from neighbours by framing the result as task names to be reused, which separates it from list_gradle_tasks/list_gradle_projects.

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 follow-on usage: pass the variant as task= to gradle_build/build_and_run to disambiguate a multi-flavor project. It also names the when-not case (multi-module root has no variants) and the alternative call to use instead, task="<module>:tasks" sourced from list_gradle_projects.

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 and openWorldHint=false, so the safety profile is covered. The description adds only that the filter is a substring match and that results are package names; it says nothing about empty results, ordering, or multi-device behavior beyond what the schema's serial parameter already states.

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 that front-loads the core action and follows with the intent, with no redundant or filler wording.

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

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

For a simple two-parameter read tool with full schema coverage and safety annotations, this is nearly complete: it establishes what is listed, how filtering works, and why an agent would call it. Only minor gaps remain, such as result ordering or behavior when no packages match.

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 fully documented in the schema, including the single-device fallback for serial. The description's 'optionally filtered by substring' merely restates the filter parameter, so the baseline of 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 and resource ('List installed package names') plus the optional substring filtering, so there is no ambiguity about what the tool returns. It also names the concrete downstream consumers (launch_app/stop_app), which distinguishes it from generic device-inspection 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?

Gives a clear when-to-use: confirming an app is installed and obtaining its exact package name before calling launch_app/stop_app. It lacks explicit when-not guidance or a pointer to alternatives such as get_app_details or app_state, which could also answer some of the same questions.

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 readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely behavioral facts beyond that — it terminates rather than streams, defaults to 400 lines, strips chatty spam, and uses the device clock for since windows. It stops short of describing pagination/truncation behavior when the dump is large, so a 4 rather than 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 core behavior, then the diagnostic use case, then the termination caveat — a sensible order. It is on the long side and repeats the "chatty emulator / 400 lines can span seconds" point that also appears in the since schema field, which is a small redundancy rather than a real flaw.

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?

Seven optional parameters, no output schema, and thin annotations — the description carries the load well, covering selection strategy, filter composition, redaction expectations, and the fact that output is a finite dump. An agent has everything needed to call it correctly on the first try.

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

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

Schema coverage is 100%, so the per-parameter baseline is 3. The description still adds cross-parameter meaning the schema only implies: lines is ignored when since is supplied, tags are OR'd while filter/priority narrow further, and the rationale for choosing since over lines on a chatty emulator.

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 ("Dump recent native log lines") and immediately bounds scope with the two selection axes (last N lines or since-based window). It also distinguishes itself from the streaming siblings by stating "Dumps and exits (does not stream)", so an agent can separate it from start_logcat_capture/stop_logcat_capture without inspecting other schemas.

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

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

Gives a concrete when-to-use scenario ("when the UI only shows a generic 'X failed' alert") and a concrete recipe (filter by app tag or 'Exception'/'Caused by', read the Caused by line). The non-streaming clause implicitly routes streaming needs elsewhere, but no sibling tool is named explicitly, 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?

Annotations only declare openWorldHint=false and destructiveHint=false, so the description carries the rest of the behavior burden. It correctly discloses that the hold duration is what defines the action and that coordinates are true device pixels, but says nothing about whether the gesture blocks, what the default hold is derived from, or what happens if the target widget has no long-press handler. Adequate 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?

A single front-loaded sentence with zero padding; the unit clarification and the use cases both earn their place. Slightly compressed by the em-dash construction, 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?

This is a low-complexity input tool with full schema coverage, non-destructive annotations, and no output schema, so the description does not need to explain return values. It covers what the gesture is and when it applies; only multi-device behavior and blocking semantics 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 description coverage is 100%, so all four parameters are already documented including the 600ms default and the serial targeting rule. The description only restates the pixel-unit convention for x/y, adding essentially no meaning beyond the schema — 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 states a specific verb+resource ('press and hold a coordinate') plus the distinguishing characteristic of a hold duration, and enumerates concrete outcomes (context menus, drag handles, long-press actions). It implicitly separates itself from the sibling 'tap' by the hold semantics, though it never names tap/swipe/drag to make the boundary 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?

The use-case list ('for context menus, drag handles, and long-press actions') gives implied guidance on when to reach for this instead of tap or drag. There is no explicit when-not statement, no mention of prerequisites, and no named alternative among the many input siblings.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false, so the description carries the real burden and delivers: it discloses the mechanism (a synthesized MENU key event), the target (foreground app), and the resulting UI state that must be navigated afterwards. It stops short of stating failure behavior — e.g., what happens when the foreground app is not a dev build and no menu appears — which is the one gap an agent might hit.

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

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

Two sentences with no filler: the action and mechanism come first, the contrast with the sibling second, the follow-up step last. Every clause carries information that changes how an agent calls it.

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-optional-param, no-output-schema tool this is close to complete — it explains the triggering mechanism and the required follow-up interaction. Only the no-menu/failure case is unaddressed, a minor omission given the tool's simplicity.

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

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

Schema coverage is 100% and the single 'serial' parameter is fully documented in the schema, including the optional-when-one-device-attached rule. The description adds nothing about the parameter, so the baseline of 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?

Names a specific verb and resource ('Open the React Native dev menu') and even the underlying mechanism (KEYCODE_MENU on the foreground app), which makes it immediately distinguishable from generic input tools like press_key or input_key_combo.

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 names the alternative (reload_app) and the condition under which this tool wins ('when reload_app's broadcast doesn't apply'), and then routes the agent forward to tap_on_text or describe_ui to select a menu item. Both when-to-use and what-to-do-next are covered with no inference required.

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

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

Annotations only declare openWorldHint and destructiveHint=false; the description adds real behavioral context by disclosing that this is an ACTION_VIEW intent issued via am start, so an agent knows it hands off to whatever app resolves the link rather than controlling the target itself. It does not cover what happens when nothing resolves the URL, but the mechanism disclosure is substantive.

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

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

A single front-loaded sentence states the action, the mechanism, and the optional package in one pass with no filler. The em-dash aside is slightly loose but still earns its place by clarifying the deep-link use case.

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

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

For a three-parameter tool with full schema coverage and safety annotations, the description covers the essentials: what it does, how it dispatches the intent, and device/package targeting. Only failure semantics for unresolvable links are absent, a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description only echoes that a package can optionally be targeted, adding no syntax examples or behavioral notes about how pinning a package interacts with link resolution.

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 ('Open a URL or deep link') and names the underlying mechanism (ACTION_VIEW / am start), which clearly separates it from launching an app package or opening a dev menu. It stops short of explicitly naming the sibling it differs from (e.g. launch_app), so it lands just under the top band.

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 clause 'the way to jump straight to a deep-linked screen' implies the use case but never states when to prefer this over launch_app or open_dev_menu, nor any exclusions. Usage has to be inferred from the phrasing.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false; the description adds real behavioral context beyond that: the underlying mechanism (adb emu gsm), the emulator-only restriction, and the fact that "call" rings an incoming call while the other actions transition an already in-progress call. It does not disclose error behavior (e.g. what happens if "accept" is sent with no ringing call), so it is not fully transparent.

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: mechanism, per-action semantics, then use case plus constraint. The most decision-relevant facts (what it does, emulator-only) are front-loaded and 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?

For a 3-parameter tool with full schema coverage, existing annotations, and no output schema, the description supplies the mechanism, the action lifecycle, and the emulator-only constraint. It is nearly complete, with only failure/edge-case reporting 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 description coverage is 100%, so all three parameters, including the full action enumeration, are already documented in the schema. The description restates the same action semantics without adding format details, side effects, or defaults beyond what the schema already provides, so the baseline of 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 and resource ("Drive an emulated voice call (adb emu gsm)") and enumerates the action transitions, so the agent knows this places/manages a voice call rather than an SMS or generic input. It stops short of naming the nearest sibling (send_sms) as an alternative, so differentiation is inferred from the resource 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?

"Use to test call-interruption behaviour and CALL_PHONE flows" gives a concrete use case, and "Emulator-only" states a hard applicability constraint, which is the key gating information for an agent choosing between tools. No explicit when-not or named alternative is provided, which keeps it below a 5.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false; the description adds meaningful behavior beyond that — this is a best-effort 'try' whose success depends on the prompt implementation, and the outcome must be verified with describe_ui. It does not say what a failed attempt returns or whether the prompt is left in a changed state, but the reliability caveat is the important one.

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: the primary mechanism first, then the failure mode and required verification step. Every clause carries operational weight.

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 UI action with no output schema and non-destructive annotations, the description supplies everything needed: how it works, when it may not work, and the exact follow-up call to confirm state before entering the PIN.

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 a single optional parameter ('serial') and the schema documents it at 100% coverage, including the 'optional when exactly one device is attached' rule. The description adds nothing about device targeting, so the baseline of 3 applies — the schema carries this dimension.

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 (move a standard BiometricPrompt to its PIN/password fallback) via two concrete mechanisms (an explicit system button or BACK as cancel path). It clearly positions itself upstream of enter_pin, so an agent can distinguish it from the sibling that actually types the PIN.

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 when-to-use context is explicit: standard BiometricPrompt needing fallback, followed by describe_ui verification and then enter_pin. It also flags the exclusion case implicitly by warning that app-controlled prompts may suppress or rename the option, though it does not name an alternative tool for that scenario.

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

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

Beyond the supplied annotations, it discloses important behavioral caveats: a key may be silently consumed with no effect, verify_change=true reports ui_changed at the cost of extra hierarchy reads, and power toggles the screen rather than reliably waking it. This adds meaningful operational context for a key-press tool with minimal annotation coverage.

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

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

The description is front-loaded with the core action and remains dense with useful guidance. It is somewhat long and repeats the key-name list already present in the schema, but every sentence contributes operational value and no major 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?

For a three-parameter tool with no output schema, the description is complete: it explains accepted key forms, key behavioral edge cases, the verify_change result, and the batching alternative. An agent has enough information to choose and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents key, serial, and verify_change. The description still adds useful semantics beyond the schema, especially the distinction between wakeup, sleep, and power, and the silent-consumption scenario for verify_change; it does not add anything for serial, which keeps it from a 5.

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: pressing a hardware/navigation key by name or raw Android keycode. It lists concrete key names (enter, back, home, power, wakeup, sleep) and distinguishes behavior from siblings by naming run_sequence for batching and clarifying power vs. wakeup.

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

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

It gives explicit when-to-use guidance: enter to submit a form, escape to dismiss the keyboard, back to go back. It also names alternatives and exclusions: use wakeup rather than power to turn the screen on, sleep to turn it off, and run_sequence for batching or timing-sensitive presses.

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

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

The annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is carried by structured data. The description adds mechanism (adb pull) and retrieval examples but never explains the striking thing about this tool: why it is marked destructive, i.e. whether an existing local file at local_path is overwritten, and what happens on a missing device path.

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 sentence, front-loaded with the action and destination, with the adb equivalent and use cases tucked into a compact parenthetical. 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?

A three-parameter, no-output-schema tool with decent schema coverage; the description covers the what but leaves the destructiveHint unexplained, which is the one behavioral fact an agent would want before calling. Adequate but with a clear gap around overwrite and failure behavior.

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

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

Schema description coverage is 100%, including the serial parameter's note that it is optional when exactly one device is attached, so the schema carries parameter meaning fully. The description adds nothing per-parameter, making the 3 baseline 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 with explicit directionality: "Copy a file off the device to a local path (adb pull)." The direction phrase distinguishes it cleanly from the push_file sibling without needing to name it, and the parenthetical grounds it in the concrete adb operation.

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 examples ("generated file, database, or screenshot") give concrete situations that select this tool, which is more than most definitions offer. It stops short of explicit exclusions or a direct contrast with push_file, so an agent must infer the inverse case.

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 openWorldHint=false, so the description only needs to explain why a 'copy' is destructive — namely that an existing file at device_path is overwritten — and it does not. The adb push equivalence and use-case examples add some context beyond annotations, but the most important behavioral fact is left implicit.

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, then the mechanism, then examples; nothing is redundant. The parenthetical and trailing example are compact and earn their 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 simple three-parameter tool with full schema coverage this is close to sufficient, but a destructive write tool should state overwrite semantics and any precondition (writable destination, connected device). Those gaps leave the agent relying on annotations to infer risk.

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%, including the serial-to-device matching rule and an example destination path, so the schema carries the parameter burden. The description adds only a loose framing of the two required paths and no new semantics such as whether parent directories are created.

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 ('Copy a local file onto the device') and anchors it to the underlying mechanism (adb push) with concrete example uses. It does not name the obvious sibling pull_file, so the direction of the transfer must be inferred from the name 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?

The examples ('seed test data or a file to import') imply when to reach for this tool, but there is no explicit when-not guidance and no mention of pull_file as the inverse operation. An agent has enough to guess the use case but no routing 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 only declare destructiveHint=false and openWorldHint=false; the description adds substantial context beyond that: best-effort semantics, silent no-op on newer RN/Expo dev clients, and the trap where a reload without adb_reverse lands on the embedded bundle. It doesn't spell out whether the broadcast is scoped to the given package's receiver beyond the action name, but the failure modes are unusually well 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?

Front-loaded with the core action and the best-effort caveat, then prerequisite. It is dense and every sentence carries information, though the long parenthetical sentence about Metro reachability is slightly harder to parse than it needs to 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 two-parameter, no-output tool this is complete: it covers what the tool does, when it silently fails, what to do instead, and the prerequisite that determines whether the reload is meaningful. An agent has everything needed to call it correctly or route around 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 description coverage is 100%, so both serial and package are already documented in the schema. The description adds related context (Metro port 8081 via adb_reverse, app_state for bundle inspection) but nothing that further clarifies these two parameters themselves, 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 and resource: trigger a Metro/JS reload on a React Native dev-client build via the RELOAD_APP_ACTION broadcast. It immediately distinguishes itself from siblings by naming open_dev_menu and tap_on_text as the fallback path.

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 states when it works (debug builds, classic non-bridgeless architecture with a registered receiver) and when it fails silently. It names the concrete alternative (open_dev_menu then tap_on_text("Reload")) and the prerequisite step (adb_reverse {device_port: 8081}).

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

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

The annotations only cover readOnlyHint and openWorldHint, so the description carries the real weight here, and it adds substantial context: what the three headline numbers mean together, why they argue an unvirtualised list, and the counter-zeroing effect of reset. It does not mention cost or latency, and reset=true arguably mutates device telemetry state under a readOnlyHint, though that tension is disclosed rather than hidden.

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 what-it-does clause is front-loaded before the comparison and the reset note, and every sentence is task-relevant. It runs dense and relies on heavy capitalization for emphasis, which costs a little readability but not correctness.

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 what comes back, and it does so explicitly by listing the returned metrics and their interpretation. Combined with the read-only annotation and full param coverage, an agent has everything needed to call and read this tool correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including reset's zeroing semantics. The description reinforces reset's intent ("measure one specific interaction") but adds no new syntax or format detail beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ("count an app's REAL view tree and recent frame health") and immediately enumerates the concrete outputs: total views, render-node kB, per-window breakdown, jank percentage, frame-time percentiles, and skipped-frame tally. It also explicitly separates itself from describe_ui, so the agent can tell the two apart without opening either schema.

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

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

It gives an explicit routing rule ("Use this — not describe_ui — to MEASURE a screen") plus the reason describe_ui fails for this job: viewport scoping drops off-screen ScrollView children, so it undercounts even at filter="all". It also tells when to set reset=true, namely to attribute jank to one interaction rather than the whole session.

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=true, so the safety profile is covered structurally. The description adds genuinely new behavioral context the annotations cannot convey: that revoking certain permissions kills the app process, which directly affects how an agent should sequence subsequent steps. It does not describe the response shape, but with no output schema and the key side effect flagged, this is a strong contribution.

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 plus a one-line caution, with the action front-loaded and the purpose and pairing packed into the first sentence. Nothing is padding; the process-kill warning earns its sentence because it changes agent 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?

For a three-parameter tool with full schema coverage and no output schema, the description covers what is needed: what it does, why to call it, its complement, and its most dangerous side effect. The only gap is what happens when the permission was never granted (error vs. silent no-op), which would be nice but is not essential to invoke it correctly.

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

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

Schema description coverage is 100%, so package, permission, and the optional device serial are already documented in the schema, including the permission-name format example. The description adds no additional meaning about parameter formats, defaults, or interactions, 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 gives a specific verb and resource ('Revoke a runtime permission from an app') plus the underlying mechanism ('pm revoke'), and it names the sibling it is the inverse of ('Pairs with grant_permission'). An agent can distinguish it from grant_permission and from unrelated app-lifecycle tools 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?

It states concrete situations for use — testing the denied permission path or forcing the permission-request dialog to reappear on next use — and points to the complementary tool grant_permission. It stops short of explicit when-not guidance (e.g., revoking a permission the app never declared), but the positive guidance is clear enough to select the tool.

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

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

The annotations cover the safety profile (destructiveHint=false, openWorldHint=false), so the bar is lower, but the description's core behavior — 'next orientation', i.e. each call advances the orientation cycle (portrait→landscape→…) — conflicts with the declared idempotentHint=true, since a second identical call does not leave the device in the same state. The useful added context (state loss on rotation, emulator-only failure mode) is real but is undercut by this inconsistency.

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 tight sentence with the verb front-loaded, a parenthetical for the underlying command, and the emulator-only qualifier at the end. No filler, though the ordering means the hard constraint appears last.

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-optional-param, no-output-schema tool, the description covers purpose, mechanism, scope limit, and a key side effect (layout/state loss). Only the discrepancy with the idempotency annotation 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?

There is a single optional parameter and schema description coverage is 100%, so the schema already explains that serial maps to adb -s and is unnecessary when one device is attached. The description adds nothing about the serial parameter; the baseline of 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 and resource ('Rotate the emulator to its next orientation') and even names the underlying mechanism (adb emu rotate). The 'Emulator-only' tag separates it from general device helpers like press_key or set_dark_mode in the sibling list.

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 concrete use case — exercising landscape/portrait layouts and rotation-driven state loss — plus an explicit exclusion ('Emulator-only'), so the agent knows not to call it on a physical device. It stops short of naming a fallback for non-emulator targets, so it is not a full when/when-not/alternative statement.

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

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

Adds real behavior beyond the annotations: foreground execution, multi-minute duration, device prerequisite, and return content (per-suite timing, failure stack traces). The one gap is that annotations declare destructiveHint=true and the description never explains what is destructive (app install/data on device, test artifacts), leaving the agent to infer the blast radius.

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 action and default task, then prerequisites, then the long-run escape hatch. No filler; each clause carries operational 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?

No output schema exists, and the description compensates by describing both return modes (human-readable summary vs. json=true structured summary). Combined with the device prerequisite and runtime warning, an agent has everything needed to call it correctly or defer to gradle_build.

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

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

Schema coverage is 100%, so all four parameters are already documented, and the description only restates the default task and the json flag. It adds no syntax or constraint detail (e.g. how args interacts with task) beyond the schema.

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

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

States a specific verb and resource ('Run Gradle instrumented (on-device) tests') and names the concrete default task 'connectedAndroidTest', which pins down exactly what executes. It is clearly separable from run_unit_tests (JVM tests) and gradle_build (generic build runner) named later in the text.

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 prerequisite ('requires a booted device/emulator') and an explicit routing rule: for long runs use gradle_build with task=connectedAndroidTest and background=true, then read the log. Both when-to-use and when-to-use-something-else are 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 only declare openWorldHint=false and destructiveHint=false, so the description carries most of the burden and does well: it discloses abort semantics ('A non-optional step error stops the rest'), the optional-flag escape hatch, guard behavior, the per-step result shape (ok/skipped/error with elapsed_ms) and the final hierarchy capture. It omits practical limits such as maximum sequence length, overall timeout behavior, or how timing jitter is handled if any step blocks.

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 value proposition, then the timer rationale, then mechanics and return behavior in a single dense paragraph. The inline example sequence is long but earns its place by demonstrating guards and assertions; the step-action enumeration partially duplicates the schema's 'steps' description.

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

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

For a complex orchestration tool with nested step objects and no output schema, the description covers what an agent needs: purpose, when to prefer it, how guards and optional work, abort behavior, and what comes back (per-step status plus final hierarchy). Little is left indeterminate before calling 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 100% and each nested step property is already documented in the schema, so the description only reinforces what is there. It does add semantic value by showing if_present used as a conditional cancel ('if_present:biometric') and by pairing optional with abort behavior, but the per-field meanings remain the schema's job.

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 ('Run several interaction steps in ONE call') and immediately distinguishes itself from siblings by eliminating agent round-trips between steps. The inline example sequence makes the scope concrete enough that an agent can choose it over calling tap/wait_for_text individually.

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 names the situations that select this tool: scripted flows and, 'crucially,' flows driven by native timers where per-step round-trips would perturb timing, illustrated with a biometric-prompt scenario. It effectively contrasts with the single-step siblings (tap, key, wait_for_text, describe_ui) without needing to list them.

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

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

Annotations only supply title, openWorldHint=true and destructiveHint=false, so the description carries most of the behavioral burden and does so well: it discloses that the tool runs in the foreground and blocks until Gradle finishes, that the default 'test' task expands to every variant on Android (roughly doubling time), and what the output contains. The main remaining gap is what happens on Gradle failure, timeouts, or a missing gradlew, which matters for a blocking build tool – keeping it from the top score.

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 return value, then the variant-timing caveat, then the alternative tool, then the json flag. Dense but each sentence carries actionable content; the single unbroken paragraph makes it slightly harder to scan than a bulleted form would.

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 correctly describes the return shape (summary, per-suite timing, failing-test stack traces) and the JSON alternative. Combined with the default-task and blocking-run disclosures, an agent has everything needed to invoke it correctly on both plain JVM and Android projects.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds concrete meaning on top: an example value for task ("testDebugUnitTest", and the ':app:' prefix form for multi-module builds), the effect of json=true (structured summary), and the session-pinned default for project_dir. It does not discuss the args parameter, which stays with 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 and resource ('Run Gradle JVM unit tests ... in project_dir') plus the returned artifact (result summary, per-suite timing, failing stack traces). It also implicitly separates itself from run_instrumented_tests by naming 'JVM unit tests' and from gradle_build by pointing to it only for background runs.

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?

Explicit when/when-not routing: pass task="testDebugUnitTest" to avoid running every Android variant, and use gradle_build with background=true instead when the run is long. The json=true option is also given a use condition, so the agent can choose among alternatives without 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 only declare destructiveHint=false and openWorldHint=false; the description adds the substantive behavior: writes a fixed file set, refuses non-empty destinations, conditionally generates the Gradle wrapper, and reports when it could not. It also discloses a downstream consequence — that all Gradle tools drive ./gradlew and will fail until `gradle wrapper` is run. That is real value beyond the structured fields.

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 artifact list, then constraints, then the wrapper prerequisite. Dense and purposeful, though the final sentence is a long compound clause that could be split for readability.

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

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

For a scaffolding tool with thin annotations and no output schema, this covers everything an agent needs: what is produced, the destination precondition, failure behavior on non-empty directories, and the gradle-wrapper dependency that determines whether the result is immediately buildable.

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

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

Schema description coverage is 100%, so each of the three parameters already carries its own definition, making 3 the baseline. The description reinforces the destination constraint ('new empty directory') and the package/app-id relationship, but adds no format or validation detail not already 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?

Specific verb + resource ('Create a minimal Kotlin Android application') with an enumerated artifact list (Gradle Kotlin DSL files, manifest, launcher Activity, resources, README, gitignore). It is clearly distinguishable from siblings like gradle_build or build_and_run, which operate on an existing project rather than generating one.

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 the operative condition ('in a new empty directory') and a hard constraint ('never overwrites a non-empty directory'), plus the follow-up path into gradle_build and the fallback when no system gradle exists. It stops short of explicitly naming an alternative tool or stating a when-not-to-use case, but the context needed to choose it is present.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond them: auto-downscaling with a default cap, auto-retry on all-black frames, the FLAG_SECURE/sleeping-display failure explanation, and multi-display foldable handling. These are exactly the operational traits an agent needs to interpret a failed or degraded capture.

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 the most important rule (screenshot after every action), then layers caveats. Dense but nearly every clause carries distinct information; the multi-display sentence is the only part that could be trimmed since the schema covers it.

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 compensates by describing the return (a downscaled PNG), the failure mode (black frame with cause), and the fallback tool. For a zero-required-parameter capture tool, an agent has everything needed to call it and interpret results.

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

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

Schema coverage is 100% and the schema already documents serial, display aliases, and the max_dim default/0-disables behavior, so the description largely restates it. It does add a small amount of framing (default display 'already captures correctly'), but that nuance is also present in the schema, so 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 and resource ('Capture the current screen as a PNG') plus the intent ('so you can SEE the UI state'), and explicitly distinguishes itself from describe_ui by saying coordinates must come from that tool, not this image.

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 ('call it after every action to confirm the screen changed'), a rationale for the rule (blind chaining taps the wrong screen), and a when-not/alternative path ('when black, use describe_ui instead'). Nothing 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 only declare openWorldHint=false and destructiveHint=false, so the description's contribution is meaningful: it clarifies that the message is injected into the emulator's inbox rather than sent over a real network, and that a second device is unnecessary. It could add more about timing or whether the SMS appears immediately, but the key behavioral nuance is covered.

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 clauses, front-loaded with the action and its mechanism, then the use case, then the environment restriction. The '(adb emu sms send)' parenthetical is slightly technical filler but remains short and earns its place as mechanism disclosure.

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

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

For a simple two-required-parameter tool with full schema coverage and annotations providing the safety profile, the description supplies what is needed to call it correctly: purpose, mechanism, use case, and environment constraint. No output schema exists, so return-value explanation is not required.

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

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

Schema description coverage is 100%, so all three parameters — including the optional serial — are already documented with examples in the schema. The description's restatement of 'from' and 'text' adds no syntax or format detail beyond that, 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 and resource ("Deliver an incoming SMS to the emulator") and even discloses the underlying command (adb emu sms send). It does not explicitly contrast with the sibling phone_call, but the injection-of-SMS framing combined with "Emulator-only" makes the scope unambiguous.

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

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

It gives a concrete usage scenario — driving OTP / 2FA flows without a second phone — which tells the agent exactly when this is the right tool. It states the emulator-only restriction, though it does not name an alternative for physical devices or a when-not case beyond that constraint.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral nuance beyond that: after clearing, parameters are required on every call again, except serial still falls back to the single-attached-device default, which the annotations do not express.

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 redundant framing; the parenthetical fallback rule is the only slightly dense element but it earns its place by preventing a wrong mental model of post-clear 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?

For a zero-parameter, idempotent state-reset tool with annotations and no output schema, this is nearly complete. A brief pointer to session_show_defaults for inspection would close the last 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?

The tool takes zero parameters, so the baseline is 4. The description appropriately spends no words on parameter semantics and instead describes the effect on parameter requirements elsewhere.

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 ('clear') and resource ('project_dir/serial defaults pinned for this session'), so the agent knows exactly what state is being reset. It doesn't name the sibling tools session_set_defaults or session_show_defaults, so explicit differentiation is absent, but the semantics are unambiguous.

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

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

The description conveys the outcome of calling it (reverting to requiring defaults on every call), which implies when you'd want it, but it never states a when-to-use condition or points to session_set_defaults as the inverse operation. Usage is inferable rather than guided.

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 idempotent, non-destructive, closed-world behavior, and the description adds the two facts that matter most: partial-update semantics ('Only the fields you pass are changed; omit a field to leave its current default alone') and precedence ('An explicit project_dir/serial on any individual call always overrides the session default'). It stops short of saying whether values are validated (e.g., an unknown serial) or how defaults are removed.

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 payoff, then the two rules that govern behavior. It is dense but every clause carries information; the only cost is a single long opening sentence that would read better split.

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

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

For a two-optional-parameter session setter with full schema coverage and annotations, the description covers scope, merge behavior, and precedence. The one real gap is that it never points to session_clear_defaults for unsetting, and the schema's 'leave empty to leave unchanged' wording implies there is no in-tool way to remove a default.

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

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

Schema coverage is 100% and both parameters are already documented, so the baseline is 3. The description adds genuine meaning beyond the schema by spelling out override precedence for individual calls, which the schema never states, and by reinforcing the omit-means-unchanged rule.

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?