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 covered. The description adds important behavior by noting that output is truncated to the tail, and 'arbitrary shell command' reinforces the broad side-effect potential.

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

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

The description is two tight sentences, front-loading the core action and immediately adding the most important caveat about truncated output. There is no wasted language.

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

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

For a destructive arbitrary-shell tool with no output schema, the description covers the main action, examples, and output truncation. It still omits timeout behavior and explicit alternatives, leaving meaningful gaps for safe and efficient 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 67%, with serial and command documented in the schema. The description adds useful command examples, but it does not explain timeoutSec, whose meaning is only implied by its name and default/min/max values.

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: running an arbitrary shell command on the device, with concrete examples. It is clear enough to distinguish this from specialized sibling tools, but it does not explicitly route the agent away from tools like packages_list or device_info.

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 imply usage for ad-hoc shell diagnostics and package listing, giving some context. However, there is no explicit when-to-use guidance, no exclusions, and no mention of when a specialized sibling tool would be 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?

Annotations only declare destructiveHint=false, so the description carries extra weight, and 'reinstall, keeping data' usefully explains why the operation is non-destructive and what happens to existing app data. It doesn't mention failure modes or permission requirements beyond the grantPermissions flag, leaving a small gap.

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

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

Two tight sentences, zero waste, with the core action and its data-retention behavior front-loaded before the sibling pointer. Every sentence earns its place.

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

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

No output schema exists, but this is a straightforward side-effecting action with a small, mostly documented parameter set; the description covers purpose and the APK-discovery path. Minor gaps (allowDowngrade meaning, serial requirement) are left to the schema.

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

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

Schema coverage is 75%, with most parameters (serial, apkPath, grantPermissions) already documented in the schema; only allowDowngrade lacks a description. The description adds no parameter-level detail, 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 (install/reinstall) and resource (APK on a device), and adds the useful nuance that a reinstall keeps data. An agent can distinguish this from siblings like app_uninstall or app_launch 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?

'Use project_apks to find built APKs' explicitly routes the agent to the sibling that supplies the required apkPath. However, there is no guidance on when not to use this tool or how it relates to app_launch/app_uninstall, so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the full burden, yet it only states that a launch happens and launch time is reported. It doesn't disclose the default force-stop (cold start) side effect exposed by stopFirst, what 'launch time' means, what happens if the package isn't installed, or whether an already-running instance is killed.

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 tight sentence that front-loads the core action and the launcher-activity default. There is no wasted text, though the compression leaves behavioral gaps rather than filling them.

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 mutation tool with no annotations and no output schema, the description is minimally viable. It omits device targeting behavior, cold-start semantics, and failure modes, so an agent could call it but would be guessing at side effects.

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, including serial selection and the stopFirst cold-start default, are documented in the schema. The description only echoes the activity-vs-launcher distinction already covered there, so it adds nothing beyond the structured fields.

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 (start) and resource (an app's launcher activity, or a named activity) and notes it reports launch time. It doesn't distinguish itself from nearby siblings like run_app or app_stop, so an agent must infer that this is low-level ADB-style launching rather than a Gradle/IDE run.

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

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

There is no guidance on when to use this instead of run_app, app_stop, or input/emulator tools, nor any preconditions such as the app being installed or a device being selected. The agent is left to infer usage entirely.

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

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

Annotations already declare destructiveHint=true, so the safety bar is lower. The description adds that data clearing is optional and wipes all app data, which is useful framing, but it does not state that force-stop itself kills the running process (and any unsaved state) or that the data wipe is irreversible and leaves the app 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?

A single front-loaded clause naming the action and its optional destructive variant, with zero filler. Nothing is repeated and the destructive option is signalled early enough to shape the call.

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 3-parameter tool with full schema coverage, an annotation for destructiveness, and no output schema, the description is close to sufficient. The remaining gap is not clarifying that clearData wipes data while keeping the package installed, which is the one point that could be mistaken for app_uninstall.

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 'pm clear' semantics of clearData and the serial default — are already documented in structured data. The description only restates the optional clearData concept, adding no syntax or device-targeting detail 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: 'Force-stop an app', with the optional data-wipe scope. It is clear what the tool does, but it never distinguishes the operation from nearby siblings such as app_uninstall (remove app) or app_launch (start it), leaving that contrast implicit.

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

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

Usage is only implied by the verb — an agent infers you call this to terminate a running app. There is no statement of when to prefer this over app_uninstall or how clearData changes the decision, and no prerequisites named in the description (the serial/device-online condition lives only in the 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 destructiveHint=true, so the destructive nature is covered. The description adds only the scope phrase 'from a device' and does not disclose the critical behavior that app data is wiped by default (keepData defaults to false), nor whether the operation is reversible or requires permissions. Minimal value beyond 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?

One front-loaded sentence with zero wasted words. It is efficient, though its terseness is the source of the missing detail rather than a model of completeness.

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 destructive mutation with no output schema and an undocumented keepData parameter whose default destroys app data. For that complexity level, the description should explain data-loss implications and result behavior, but it supplies none of 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 67%: serial and package are documented in the schema, but keepData has no description at all despite controlling whether user data survives. The description provides no parameter semantics and therefore fails to compensate for the uncovered destructive parameter.

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

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

States a specific verb ('Uninstall') and resource ('an app package from a device'), which cleanly distinguishes it from siblings like app_install and packages_list. It does not explicitly name or contrast with any sibling, but the action is unambiguous.

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

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

There is no guidance on when to use this versus alternatives such as packages_list (to inspect before removing) or app_install (to reinstall), nor any prerequisites such as device being online. Usage must be inferred entirely from the verb.

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

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

With no annotations at all, the description carries the full burden, and it does deliver the key output contract: compiler errors and the APK path. It omits important behavioral traits an agent needs — that the call blocks for a bounded time before returning, that an in-flight build must be polled via job_status, and that the build has side effects on disk. Those gaps are partially covered by the waitSec parameter description but not by the tool description 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?

A single front-loaded sentence: the action and artifact come first, then scope and defaults, then the return contract. No filler, and a reader can act on it after one pass.

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

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

There is no output schema, so the description correctly names what comes back (compiler errors, APK path), and the schema fully documents the long-running/polling mechanics via waitSec and job_status. What remains missing is only a note on which sibling to reach for when the build should be run differently.

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 with defaults, patterns, and ranges, establishing the baseline of 3. The description restates the module and variant defaults, adding light confirmation but no new semantics beyond what the schema provides.

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

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

States a specific verb and artifact ('Assemble an APK') plus the two selector dimensions (module, variant) and their defaults, which is concrete and actionable. It does not differentiate itself from adjacent siblings such as gradle_run or gradle_tasks, so an agent must infer that this is the build-specific path rather than a generic Gradle invocation.

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 defaults ('the app module, debug') imply the common case and make the zero-argument call safe, which is genuine usage guidance. However there is no explicit when-to-use framing, no exclusion of gradle_run/gradle_tasks, and no statement of prerequisites (e.g. a prior Gradle sync).

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds nothing beyond that: it doesn't say whether it errors when multiple devices are online without a serial, whether an emulator qualifies, or how failures surface.

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

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

A single sentence that front-loads the returned fields with zero filler. It is efficient, though it reads as a return-value list rather than a statement of purpose.

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

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

With no output schema, the description usefully enumerates what comes back, which is the main gap it needed to fill. Missing only edge-case behavior (multi-device ambiguity, offline devices), which the schema partially covers.

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 documented in-schema with its optionality rule. The description adds no 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?

The description enumerates exactly what the tool reads (model, Android version, API level, ABI, screen size, density), which makes the resource unambiguous. It lacks an explicit verb and does not distinguish itself from siblings like devices_list or environment, so an agent must infer it is a metadata read, not a listing.

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

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

No guidance on when to call this instead of devices_list or environment, and no stated preconditions such as a device being online. The only usage hint (serial optional when one device is online) lives 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?

readOnlyHint=true already tells the agent this is a safe read. The parenthetical 'adb devices -l' adds real context by implying the familiar adb output shape (serial, state, model/device columns), but nothing is said about what happens with no devices connected or whether the list is cached/live.

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

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

A single front-loaded sentence with no filler; the parenthetical command reference earns its space by hinting at output format.

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 no-parameter read tool with no output schema, the description plus the adb command reference gives an agent enough to invoke it correctly. The only miss is not clarifying the overlap with emulator_list/device_info.

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?

Zero parameters, so the baseline is 4; there is nothing parameter-related for the description to compensate for and it correctly does not invent any.

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 connected Android devices and running emulators') and even names the underlying command, so the intent is unambiguous. It does not distinguish itself from the sibling emulator_list or device_info, both of which overlap with this territory.

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

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

There is no statement of when to call this instead of emulator_list (also emulator-focused) or device_info (per-device detail). The agent must infer from the name alone that this is the discovery step before app_launch, adb_shell, or logcat.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds meaningful context beyond annotations by specifying that results include running status and serials, which is especially valuable because there is no 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?

A single front-loaded sentence that states the resource, scope, and key return detail with no wasted 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 simple zero-parameter read tool, the description covers the core purpose and the key output elements (running status and serials). It could be slightly more complete by noting whether stopped/offline AVDs are also included or by distinguishing it from devices_list, but it is otherwise adequate.

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 are zero parameters, so there is nothing for the description to clarify. The baseline for a zero-parameter tool applies, and the description appropriately does not invent parameter details.

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 Android Virtual Devices', and adds the useful detail of showing which are running with serials. It does not explicitly differentiate itself from sibling tools such as devices_list or device_info, which is the main gap.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives like devices_list, device_info, or emulator_start/stop. Usage is only implied by the tool's purpose, with no exclusions or prerequisites 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?

No annotations, so the description carries the burden. It usefully discloses the async job model and the polling contract, which the schema cannot express. However, it omits other behavioral facts an agent needs: that behavior when an AVD is already booted, that wipeData is irreversible (only implied by the schema's parenthetical), and roughly how long a boot typically takes.

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

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

Two sentences, zero filler, and the async/polling contract is front-loaded immediately after the core action. Every clause earns its place.

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

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

With no output schema, the description does state that a job is returned, covering the most important return-value gap. It stops short of saying what the job object contains (id, status) or how to interpret a completed vs pending job, which is the only meaningful omission for a 5-parameter tool.

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

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

Schema coverage is 100% and each parameter carries a clear description, so the schema does the heavy lifting. The description references waitSec's role as the point after which a job is returned, adding a little meaning, but adds nothing about coldBoot, headless, or wipeData.

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') plus the key behavioral twist (background, waits for boot completion). It is clearly distinguishable from siblings emulator_list, emulator_stop, and job_status.

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 to job_status when the boot doesn't finish inside waitSec, which is the main follow-up decision an agent faces. It doesn't offer exclusions (e.g., what to do if the AVD is already running) or guidance on when to prefer coldBoot/wipeData.

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?

destructiveHint=true already tells the agent this is a destructive operation, so the description needn't restate safety. It adds only that the target must be running and how the serial looks; it says nothing about whether the shutdown is graceful, whether emulator state/AVD data survives, or what happens if the serial is unknown.

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 operation first and the identifier format second; nothing is redundant.

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

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

For a one-parameter tool with annotations covering destructiveness and no output schema, this is close to adequate, but the missing link between obtaining a serial and calling stop, plus no error behavior, leaves gaps.

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

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

Schema description coverage is 0%, so the description carries some burden; the inline example 'emulator-5554' usefully illustrates the serial format that the regex pattern encodes, but there is no explanation of where to obtain a serial (e.g. emulator_list).

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 ('Shut down a running emulator') and narrows to operation by serial, which clearly separates it from emulator_start and emulator_list. Only the sibling differentiation is implicit rather than named.

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

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

Usage is implied by the counterpart emulator_start and the 'running emulator' qualifier, but the description never says when to prefer this over alternatives or what precondition (emulator must exist) matters.

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

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

readOnlyHint=true already declares this is a safe read, and the description reinforces that by framing it as a report. It adds useful behavioral context by previewing the reported fields, which matters because there is no output schema, though it says nothing about failure modes when the server can't detect a toolchain.

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 content list comes first, the actionable usage cue second. Nothing repeats the name or 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 read-only diagnostic with one optional parameter and no output schema, the description supplies everything an agent needs: what will be returned, when to reach for it, and that the project is resolved on the server side. No meaningful gap remains.

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 projectDir parameter is fully documented there, including its ANDROID_PROJECT_DIR / cwd default. The description only alludes to it via "the resolved project," so the schema does the substantive work and 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 ("Report") and enumerates exactly what the resource covers: SDK path and installed packages, Android Studio install, JAVA_HOME, and the resolved project. That enumeration implicitly separates it from siblings like device_info or project_info, which concern a device or a project rather than the host toolchain.

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?

"Call this first when something isn't found" gives an explicit trigger condition an agent can act on. It stops short of naming an alternative or a when-not-to-use case, so it is clear context rather than 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?

With destructiveHint=true, the annotation already flags that this operation can overwrite data. The description adds no behavioral context beyond 'Copy a file' - it does not state that destination files may be overwritten, what permissions are required, or how errors are handled. That leaves a significant gap for a destructive file operation.

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

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

A single sentence with no filler, and the core idea - copying files in either direction between host and device - is front-loaded. Nothing is wasted, even if more detail would be useful.

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

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

For a destructive 4-parameter tool with low schema coverage and no output schema, the description is too thin. It omits direction semantics, localPath/devicePath distinction, serial behavior, and overwrite implications, leaving the agent to infer critical operational details.

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

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

Schema description coverage is only 25%, so the description must compensate but largely does not. It parenthetically references push/pull, which hints at the direction enum, but it never explains which path is local versus device-side, nor mentions the optional serial parameter's role.

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: 'Copy a file between this machine and the device', and names the underlying adb push/pull operations. This clearly distinguishes it from sibling tools like adb_shell and ide_read_file, though it does not explicitly call out those alternatives.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as adb_shell, ide_read_file, or ide_find_files. The push/pull direction is implied, but prerequisites and exclusions are 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?

With no annotations, the description carries the full burden and does disclose the two traits an agent most needs: the invocation is asynchronous (a job, polled via job_status) and the payload is 'parsed compiler errors'. It omits failure semantics — non-zero exit handling, whether output is truncated, or what happens on timeout past waitSec.

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, then return shape, then async/polling behavior. 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 four-parameter tool with no output schema and no annotations, the description covers the essentials: what it runs, what comes back, and that it is asynchronous with a polling follow-up. The remaining gap is failure/timeout behavior, which matters for a build tool but is a secondary detail.

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

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

Schema coverage is 75%, with args, waitSec and projectDir already documented in the schema. The description adds real value for the undocumented-but-required 'tasks' parameter by showing accepted shapes ('assembleDebug', ':app:testDebugUnitTest', ['clean','build']), conveying the colon-prefixed module path format the regex alone only hints at.

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 tasks through the project's wrapper') and backs it with three concrete task-list examples including module-scoped syntax. It does not, however, distinguish itself from the sibling tools 'build' or 'gradle_tasks', which an agent would reasonably consider for the same goal.

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

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

The description gives clear operational guidance for the async path ('Runs as a job; poll with job_status if still running'), which tells the agent what to do after invocation. It offers no guidance on when to pick this over 'build' or 'gradle_tasks', and no exclusions or preconditions such as needing a valid project directory or a completed Gradle sync.

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, so the safety profile is covered; the description adds almost nothing beyond that. It doesn't say whether the listing is fast/cached, whether it depends on a Gradle sync state, or what the output looks like (no output schema exists).

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

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

A single short sentence with no filler, front-loaded with the verb and resource. It is efficient, bordering on under-specified rather than bloated.

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

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

For a tool with an undocumented 'all' flag, no output schema, and no stated prerequisite (e.g., that a project dir must exist or Gradle must be syncable), the one-sentence description leaves the agent guessing about output shape and the meaning of the boolean option.

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

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

Schema coverage is 67%: module and projectDir are documented in the schema, but the 'all' boolean has no description anywhere. The description mentions module scope only obliquely and never explains that setting 'all' includes tasks from all subprojects, leaving a meaningful option ambiguous.

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 Gradle tasks') and notes the project-or-module scope. It is distinguishable from siblings like gradle_run or build by the verb 'list', though it never names those alternatives explicitly.

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

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

No guidance on when to call this versus gradle_run, build, or project_info, and no hint that listing is typically a precursor to running a task. The parenthetical '(or one module)' implies a scenario but doesn't state when or why to choose it.

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

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

Annotations already declare destructiveHint=true, so the safety profile is carried by structured data. The description adds the useful scoping fact that editor actions target the active editor, but does not warn that menu actions can modify files or trigger builds (long-running, irreversible), which would be valuable context 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?

Front-loaded with the core action, then the id examples, then the editor caveat. Every sentence carries information; only the mid-sentence id enumeration is slightly list-like, but each entry 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?

No output schema exists, so the description should explain what invoking an action returns or whether it blocks until completion — it does not. For a destructive, arbitrary-menu-dispatch tool with 50% schema coverage, the remaining gaps are execution semantics (sync vs async, failure behavior) and the lack of a pointer to the full action-id catalog.

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 `id` parameter has no schema description (coverage 50%), so the description must compensate, and it does: it enumerates five concrete ids with meanings, including a namespaced one (Android.SyncProject) and a clarification for MakeGradleProject. It does not say where the full id list lives, but the examples add real value over the bare 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 ('Invoke an Android Studio action by id, as if chosen from the menu'), which is concrete and easy to distinguish from file-oriented siblings like ide_read_file. It does not, however, differentiate itself from ide_actions (presumably the lister) or note the overlap with ide_gradle_sync for Android.SyncProject.

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?

One explicit prerequisite is given ('Editor actions apply to the active editor; use ide_open first'), which is genuinely useful. But there is no routing guidance to sibling tools: nothing says to use ide_actions to discover ids, or that ide_gradle_sync is a dedicated alternative to invoking Android.SyncProject here.

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, so the safety profile is covered. Beyond that the description adds nothing: no statement about what is returned (ids only vs. ids plus menu text), what an empty query does, or how the limit truncates results. With no output schema, this is a meaningful gap.

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

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

A single front-loaded sentence with no filler, and the parenthetical examples earn their place by showing what a menu-text query looks like. Slightly under-specified rather than verbose.

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 lookup tool with no output schema, an agent still needs to know the shape of the results (do I get bare action ids?), what a blank query returns, and how limit affects output. The description covers the query semantics but leaves these open.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain that 'query' matches either an action id or menu text and gives concrete examples, which is genuinely useful. However, the 'limit' parameter (default 50, max 500) is never mentioned, leaving half the surface undocumented everywhere.

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: 'Search Android Studio's action ids', and clarifies that matching is by id or menu text. This is enough to distinguish it from the execution-oriented sibling ide_action, though the description never names that sibling explicitly.

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

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

Usage is only implied: the mention of action ids suggests the result feeds ide_action, but the description never says 'use this to look up an id before calling ide_action' or when not to use it. No prerequisites or exclusions are given.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful context about what editor state is returned, but it does not mention permissions, rate limits, output format, or how project scoping behaves.

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

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

The description is a single concise fragment with no wasted sentences, and the resource is front-loaded. Its fragment grammar slightly reduces clarity, but it is appropriately sized for 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?

The tool is low complexity with one optional parameter and a read-only annotation, and the description conveys the main return contents. Because there is no output schema, the description should more clearly resolve whether it returns all open files or only files with unsaved changes, and how the active file details relate to the list.

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

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

The input schema has 100% description coverage and fully documents the optional project parameter. The description does not add any parameter semantics beyond the schema, so the baseline score 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 identifies a specific resource and returned data: open files, unsaved changes, and active file caret/selection. However, it is a noun phrase without an action verb, and it does not differentiate this tool from siblings such as ide_read_file, ide_status, or ide_save_all.

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

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

There is no explicit guidance on when to use this tool versus alternatives, when not to use it, or any prerequisites. Usage can only be inferred from the described return contents.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds that results come from the IDE index (i.e., newly created or unindexed files may not appear), which is useful, but it says nothing about result ordering, truncation, or what the 'limit' cap of 1000 means in practice.

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 verb and resource, then the syntax examples tucked in parentheses. Zero 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?

A read-only three-parameter lookup needs little, and the name-syntax guidance is the core piece. However, with no output schema the description should say what comes back (paths, ranked matches, count) and how the limit interacts with the result set; that 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 only 33%; the schema documents 'project' but leaves 'name' and 'limit' bare. The description compensates well for 'name' by specifying exact vs glob syntax with examples, but adds nothing for 'limit' (default 100, max 1000), so the low-coverage gap is only partly closed.

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 ('Find project files by name') and the mechanism ('using the IDE index'), with concrete examples of both supported input styles. It implicitly separates itself from ide_find_usages and ide_read_file by being a name-lookup over the index, but never names a sibling to route against.

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

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

The exact-name vs glob examples imply how to query, and 'using the IDE index' hints that only indexed project files are searched. There is no explicit statement of when to prefer this over ide_find_usages or ide_read_file, and no 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 readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context that the lookup is semantic and language-aware rather than textual, but it says nothing about result capping (the default limit of 200), truncation behavior, or what happens when the position is not on a symbol.

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

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

A single sentence with the resource and the key differentiator front-loaded, and no filler. Every clause carries information the agent needs to pick and call the tool correctly.

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

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

With no output schema, the description should hint at what a 'reference' result looks like, and it does not (no mention of file/line pairs or result shape). Still, for a read-only lookup with a well-described position triple and a capped limit, it is nearly sufficient — the missing piece is result-format and truncation guidance.

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

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

Schema coverage is 60%: path, column, and project are documented in the schema, while line and limit are not. The description's 'path:line:column' notation clarifies how the position triple is interpreted as pointing at a symbol, but it never mentions limit or what happens when results exceed it, leaving one of five parameters unexplained anywhere.

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

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

States a specific verb ('find every reference'), the precise resource (the symbol at path:line:column), and the mechanism (IDE semantic index). It also explicitly negates the closest alternative interpretation ('not text search'), so an agent can distinguish it from ide_find_files and a generic grep.

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 'semantic index, Kotlin and Java aware, not text search' clause gives a clear condition for selecting this tool over a text/file search. However, no sibling tool is named (e.g., ide_find_files) and there are no stated exclusions such as 'use ide_rename instead if you intend to modify references'.

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

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

With no annotations, the description carries full burden but does disclose key behavior: it blocks until completion and reports success or a failure message. It omits timeout/abort semantics tied to waitSec, which matters for a 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?

A single front-loaded sentence with the action first and the return behavior second, 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?

Explains the outcome (success vs failure message) despite no output schema, which is helpful. However, given no annotations and an undocumented waitSec, the description should clarify timeout behavior and whether partial results are 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_description_coverage is 50%: 'project' is documented in-schema but 'waitSec' is not, and the description adds nothing about how long it waits or what happens on timeout. For a blocking tool, the wait parameter's meaning is left entirely unexplained.

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

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

States a specific verb ('Sync Project with Gradle Files') and target environment (Android Studio), which is concrete and actionable. It does not name distinguishing alternatives like gradle_run, gradle_tasks, or ide_sync_status, so sibling differentiation is left implicit.

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

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

The phrase 'wait for the result' implies a blocking operation usable when a sync must complete before proceeding, but there is no explicit when-to-use guidance and no mention of when to prefer gradle_tasks, gradle_run, or ide_sync_status instead.

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

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

With no annotations, the description carries the full burden. It does usefully disclose two things beyond the name: the tool acts on an already-running IDE, and it steals focus by bringing the window to the front — a real side effect worth knowing. It does not say what happens if the file or project cannot be resolved, whether a new tab is opened or an existing one reused, or whether the IDE must have that project loaded.

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 location target first and the focus effect second. Nothing redundant, nothing padded.

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

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

For a small side-effecting action on a running IDE with no output schema, the description covers what the tool does and its user-visible effect. Missing only failure/edge-case behavior (file not found, project not loaded) and tab-reuse semantics, which are minor for this tool class.

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 25% — only `project` is documented in the schema. The description, by saying 'at a line/column', gives the bare `line` and `column` integers a meaning they lack in the schema: optional navigation targets. It adds nothing about indexing base, defaults, or path format (absolute vs project-relative), so two of four parameters remain under-specified.

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 a file at a line/column) and a specific target environment (the running Android Studio), plus the focus side effect of raising the window. It implicitly distinguishes itself from ide_read_file by being a UI/editor action rather than a read, but it never names that sibling or studio_open, so the boundary is left for the agent to infer.

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 scenario (navigate the human-visible editor to a location) is implied by 'bring its window to the front', but there is no explicit when-to-use, no when-not-to-use, and no named alternative such as ide_read_file for programmatic reading. An agent must infer the choice from the verb.

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, but the description adds non-obvious behavior beyond that: it may open the file in the IDE as a side effect. The no-Gradle statement also signals cost/speed characteristics an agent can use for planning.

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 is returned, followed by the mechanism and side effect. No filler.

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

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

With no output schema, the description conveys what comes back (errors and warnings) and the side effect. It could note behavior when analysis has not finished within waitSec (partial results vs. empty) or point to the project-wide sibling, but core calling needs are met.

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

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

Schema coverage is 75% and documents path, project and waitSec well; only minSeverity lacks a schema description, and its enum values are self-explanatory. The description adds no parameter-level meaning beyond the implicit mapping of "a file" to path, so baseline 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 resource (errors/warnings for a single file) plus the mechanism (Android Studio live analysis: compiler checks, Android Lint, inspections) and an explicit exclusion (no Gradle). This distinguishes it from project-wide and build-based siblings such as ide_project_problems and lint_results.

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?

"Without running Gradle" tells the agent when to prefer this over build/lint tools, and the file-level scope is clear. It stops short of naming explicit alternatives or when-not conditions (e.g., use ide_project_problems for repo-wide issues).

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=true, the description adds real behavioral traits: it does not open the files in editors, does not run Gradle, defaults to errors only, and is cheaper/faster than a build. It does not say whether results reflect unsaved buffers, how stale cached analysis is, or what the file cap does to completeness, which keeps it below 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, no filler. The core action and its scope come first, and the differentiating speed/behavioral claims follow, so every clause earns its place.

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

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

There is no output schema, so the description should convey what comes back (a list of problems with file, location, severity, message) and how the 300-file default cap affects coverage; it does neither. The safety profile and no-Gradle/no-open behavior are covered, so the gaps are modest but real for a tool the agent may rely on for feedback.

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

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

Schema coverage is 50%: paths and project are already documented in the schema, and the description only loosely echoes them ('over the project or given files/folders'). 'Errors only by default' explains the practical effect of minSeverity, but maxFiles (default 300, cap 5000) is never mentioned in schema or description, leaving a meaningful constraint undocumented.

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

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

States a specific verb and resource: run Android Studio's analysis (compiler checks, inspections, on-the-fly lint) over the project or given files/folders. It implicitly distinguishes itself from build/gradle_run ('without running Gradle') and from ide_open ('without opening them'), but never names the closest sibling, file-scoped ide_problems, or lint_results, so the boundary still requires inference.

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

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

Gives a concrete usage context: 'faster than a build for checking an edit compiles', which tells the agent when this is preferable to a Gradle build. It stops short of explicit exclusions (e.g., 'use ide_problems for the currently open file' or 'use lint_results for a full Gradle lint report'), so there is clear context but no 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 readOnlyHint=true, and the description adds genuinely useful behavior: returned content reflects the in-memory buffer including unsaved edits, which is not encoded anywhere in structured fields. It says nothing about line-range behavior, error handling for nonexistent paths, or output shape, so it sits at adequate rather than rich.

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

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

Two tight sentences with the differentiating behavior ('as Android Studio currently has it') front-loaded and the preference rule following. 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?

With no output schema and three parameters, the description covers the core semantic (fresh buffer state) and the routing rule, but leaves two of three parameters and the return format unaddressed. An agent can call it correctly for the common case, but not for ranged reads.

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

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

Schema coverage is only 33% — just 'path' is documented as 'Absolute file path'. The description never mentions that startLine/endLine exist or that the read can be scoped to a line range, so an agent could easily miss partial-read capability. With low coverage the description needed to compensate and did not.

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

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

States a specific verb (read) and resource (file) plus the crucial qualifier 'as Android Studio currently has it, including unsaved edits', which an agent could not infer from the name alone. It distinguishes from disk reads but does not differentiate itself from sibling tools like ide_editors or ide_open, which also expose editor content.

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 selection rule: prefer this over reading from disk when the user is editing in the IDE. It stops short of saying when NOT to use it — e.g. versus ide_editors for enumerating open buffers or ide_find_files for locating a path.

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 destructiveHint=true: it discloses that all references are rewritten, that classes also get their file renamed, that all files are saved afterwards, and that conflicts surface as a Studio dialog causing a timeout that the agent cannot resolve programmatically. That timeout/dialog behavior is a critical, non-obvious trait an agent must know before calling.

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, zero filler: operation and scope first, then the file-saving side effect, then the failure mode. Every sentence carries information an agent needs.

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

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

No output schema, and the description covers the mutation's side effects, save behavior, and the timeout/dialog hazard, which is the main completeness risk. The gap is the unmentioned scope-widening boolean flags and their implication for how carefully the agent should choose line/column; minor but real for a destructive 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?

With 57% schema coverage, the description adds the key insight that line/column address a symbol name at a declaration or reference site, but it says nothing about the optional behavioral parameters searchInComments and searchTextOccurrences, which materially widen the blast radius, nor about the project default. Baseline-plus rather than full compensation.

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

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

States a specific verb ('Rename') and resource ('the symbol at path:line:column') plus the scope of the operation ('update all references') and an unusual extra ('classes also rename their file'). The Shift+F6 analogy makes the exact IDE operation unambiguous and separates it from siblings like ide_find_usages or ide_action.

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?

Clear context for use (position-addressed symbol rename with reference updates) and explicit failure guidance: if the IDE finds conflicts, a Studio dialog appears and this call times out, so resolve there. It does not explicitly name an alternative tool (e.g. ide_find_usages first, or ide_action), so it stops short of full when/when-not routing.

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

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

With no annotations, the description carries the full burden, and it does disclose a key side effect: it deploys to the IDE's selected device, taking the action out of the pure-IDE realm. It omits whether the call blocks until deployment finishes, what it returns, how to observe progress (job_status exists as a sibling), and what permissions or setup are required.

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

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

Two short sentences, front-loaded with the action and side effect before the default behavior. The parenthetical 'like its toolbar buttons' earns its place by conveying device deployment, though it could be tightened.

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

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

For a side-effecting launch tool with no annotations and no output schema, the description is just adequate: it explains what happens but leaves return values, async/blocking behavior, and failure modes unaddressed. An agent could call it, but would not know how to confirm the deployment succeeded.

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

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

Schema coverage is only 33% ('project' documented in schema only), so the description must compensate. It partially does: 'Run or debug' explains the `debug` boolean, and 'Defaults to the selected configuration' explains `name`'s default. `project` semantics beyond the schema's own text are not extended, keeping this at minimum-viable.

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 (run/debug) and resource (a run configuration in Android Studio), and clarifies the mechanism ('like its toolbar buttons'). It stops short of naming how it differs from close siblings such as run_app, app_launch, gradle_run, or ide_run_configurations, so the agent must infer the distinction.

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 closing sentence 'Defaults to the selected configuration' implies the tool can be invoked with no arguments and will act on the IDE's current selection, which is useful usage context. However, there are no explicit when-to-use/when-not statements and no routing to alternatives like app_launch or gradle_run.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context by noting that the selected configuration is reported, but it does not describe ordering, grouping, or what happens when no project has configurations.

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 definition is a single compact sentence with no wasted words. The core resource and the selected-configuration detail are front-loaded.

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

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

For a simple read-only listing tool with one fully documented optional parameter, the description is nearly complete: it says what is listed and that the selected configuration is included. A small gap remains around whether the list is scoped to debug configurations only or includes run configurations too, but otherwise an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the single optional project parameter is already fully documented. The description adds no additional parameter semantics or format details beyond what the schema provides, making the baseline score 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: list run/debug configurations, and adds that the selected configuration is included. It is clear what the tool returns, though it does not explicitly distinguish itself from the related ide_run tool that would launch one of these configurations.

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 usage is implied: inspect available run/debug configurations, presumably to choose one for ide_run. However, the description gives no explicit when-to-use guidance, no exclusions, and no direct reference to alternatives such as ide_run.

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

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

With no annotations, the description must carry the behavioral burden. It discloses that the operation writes buffers to disk and that related tools auto-save, but it does not address prerequisites (e.g., Studio connection), overwrite behavior, failure cases, or return behavior.

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

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

The definition is a single, front-loaded sentence with no wasted wording. The parenthetical adds useful operational context without bloating the 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 zero-parameter, no-output tool, the description is nearly complete: it states the action and notes automatic saving by build/run_app. A small gap remains around explicit Studio/IDE requirements 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?

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description appropriately does not invent any.

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 uses a specific verb and resource: 'Save all unsaved editor buffers to disk.' It clearly scopes the operation to unsaved buffers and is distinguishable from sibling IDE tools such as ide_editors or ide_read_file.

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 explicitly notes that build and run_app save automatically when Studio is running, which gives the agent clear context for when an explicit save may be unnecessary. It does not enumerate an explicit when-not or alternative tool, but the operational context is strong.

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

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

The readOnlyHint=true annotation already establishes the safety profile, and the description is consistent with it. It adds useful context about capture scope (whole window vs active editor, 'as the user does'), but says nothing about the returned image's format, size, or whether it reflects only currently rendered UI.

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

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

A single front-loaded sentence with no filler. The capture target comes first and the examples of what can be seen follow, so the agent gets the core action before any elaboration.

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, zero-required, read-only capture tool with no output schema, the description covers the essential decision (what to capture and why). The main residual gap is what the caller receives — raw image content versus a file reference — which matters for a screenshot tool.

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

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

Schema coverage is 50% — `project` is documented in the schema but the `target` enum is not. The description compensates by defining what each target means: the full window versus 'just the active editor area', which is more informative than the bare enum values. The `project` defaulting behavior is left to the schema.

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

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

States a specific verb and resource: 'Capture Android Studio's window (or just the active editor area) as an image.' The mention of Android Studio's own window implicitly separates it from the sibling `screenshot` (device screen), but it never names that sibling explicitly, so the differentiation is inferred rather than stated.

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

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

The enumeration of what becomes visible ('Compose previews, the layout editor, tool windows and error balloons as the user does') implies when this tool is the right choice — visual inspection of IDE state. However, there is no explicit when-not guidance and no pointer to the `screenshot` sibling for device-level captures.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context (requires the bridge plugin, reports indexing state), but omits what actually happens when Studio is not running — an error, or a running=false payload — which is the main behavioral question for a status probe with no 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?

One sentence, front-loaded with the core subject, and every clause adds information (plugin caveat, version, projects, indexing). No filler.

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

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

With no parameters and no output schema, the description carries the burden of describing return content, and it does so by enumerating the four reported fields. It stops short of stating the failure/not-running case, which is the remaining gap for an agent deciding how to react.

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 schema leaves nothing to explain; baseline is 4. The description correctly spends no words on 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?

The description names a specific resource (Android Studio via the bridge plugin) and enumerates the exact state it reports: running status, version, open projects, and indexing state. It is clearly a status/query tool, though it does not explicitly contrast itself with siblings such as ide_sync_status or project_info.

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

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

Usage is only implied: an agent can infer this is the pre-flight check before calling other ide_* tools, but the description never says when to call it or when to prefer alternatives like ide_sync_status or environment. No exclusions or prerequisites beyond the parenthetical plugin mention.

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, so the safety profile is covered. The description adds real value by enumerating the possible result states (running / succeeded / failed with error); since there is no output schema, this is the only place an agent learns what comes back. It stops short of describing error detail or whether a stale prior sync is reported.

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 resource and ends with the enumerated return states. No filler, nothing out of order.

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

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

For a one-param, annotation-covered read tool with no output schema, the definition supplies the essential missing piece: the set of possible states. It could go further on failure details or multi-project scoping, but nothing needed to call it correctly 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?

Only one optional parameter, and the schema documents it at 100% coverage with a precise defaulting rule (project containing path, else active). The description adds nothing beyond that, 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 resource and scope: the state of the most recent Gradle sync in Android Studio. This is clearly a status read, distinguishable from the mutating sibling ide_gradle_sync, though the description never names that sibling explicitly.

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

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

The word "status" implies a read-only check, which is enough to infer usage versus ide_gradle_sync or gradle_run. There is no explicit when-to-use or when-not-to-use guidance, and polling behavior (call repeatedly while 'running') 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?

With no annotations, the description carries the full burden. It does disclose the action vocabulary and valid key values (BACK, HOME, ENTER, APP_SWITCH, DEL, any KEYCODE_*), which is real behavioral context. But it says nothing about what happens on failure, whether the call blocks until the UI settles, timing/rate considerations, or what a successful call returns (there is no 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, zero filler. The capability statement comes first and the follow-up hint (ui_dump for coordinates) is a single useful clause rather than a paragraph.

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 9-parameter, mutation-style device-control tool with no annotations and no output schema, the description covers the action surface well. The remaining gap is outcome reporting and device-selection behavior, though the latter is partly documented in the serial parameter of the schema.

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

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

Schema coverage is 67% and the description fills some of the gap: it maps actions to the coordinate/text/key parameters and enumerates the accepted key names, which the schema only gestures at with 'Key name or keycode'. It still leaves the x/y vs x2/y2 start-end relationship for swipes implicit, relying on the schema's 'Swipe end x/y' notes.

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 the device UI') and enumerates exactly what it can do: tap or long-press at coordinates, swipe, type text, press a key. An agent can distinguish it from sibling tools like adb_shell, screenshot, or ui_dump without opening the schema, and the final sentence points at ui_dump as the source of coordinates.

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 actionable usage pointer — 'Get coordinates from ui_dump' — which establishes the intended workflow pairing. It does not, however, state when to prefer this over adb_shell for input injection, nor any prerequisite like a connected/online device or which device gets targeted when several are online.

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 destructiveHint=true annotation already signals this is a mutating operation, and 'Cancel' is consistent with that. However, the description adds nothing beyond the annotation: it doesn't say whether cancellation is graceful or forced, whether partial build artifacts are left behind, whether it blocks until the job stops, or what error occurs if the job has already finished. For a destructive one-param tool that is a meaningful gap.

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

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

A single front-loaded sentence with no filler, which is good structurally. But the brevity is under-specification rather than efficiency, since key facts about the id and cancellation semantics are absent.

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 destructive, no-output-schema tool with an undocumented required parameter and no stated post-conditions. Given the siblings include job_status and gradle_run, a caller needs to know how the id is obtained and what state the job ends in. The definition leaves both unaddressed.

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

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

There is one required parameter 'id' with 0% schema description coverage, so the description carries the full burden of explaining it. It never states that the id is a job identifier, where that id comes from (presumably a prior job_status or gradle_run response), or its format. This is exactly the case where the description should compensate and does not.

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

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

States a specific verb (cancel) and resource (background job), and the qualifier 'running' implies the target is an active job rather than a completed one. It is distinguishable from the sibling job_status, which inspects rather than terminates jobs. Slightly short of a 5 because it doesn't clarify what a 'job' is in this environment (build? gradle task?).

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

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

No guidance on when to cancel versus waiting for completion, and no mention of checking job_status first to confirm the job is still running. The sibling job_status is the obvious companion tool but is never referenced. The agent must infer the workflow.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavior about optional waiting and the list-all mode when id is omitted, but it does not explain blocking behavior, polling, or result details beyond what the annotation and schema provide.

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

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

Three short sentences, front-loaded with the core purpose and followed by the two key usage behaviors. There is no wasted wording.

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

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

For a read-only status/listing tool with no output schema, the description covers the essential purpose, job types, wait option, and list-all mode. Minor gaps remain around id format and wait semantics, but the definition is complete enough to call correctly.

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

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

Schema coverage is 67%, with waitSec and logChars documented in the schema. The description adds valuable meaning for the undocumented id parameter by stating that omitting it lists all jobs, but it says nothing about logChars and adds little beyond the schema for waitSec.

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: checking a background job, with examples of job types (build, run_app, emulator_start). It also clearly distinguishes two modes: checking a specific job by id versus omitting id to list all jobs.

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

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

It gives clear operational guidance: wait optionally and omit id to list all jobs. It does not explicitly name the alternative job_cancel or say when not to use this tool, but the usage context is clear enough for an agent.

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

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

readOnlyHint=true already establishes this is a safe read. The description adds the useful prerequisite that a lint report must exist first, but it doesn't say what happens if no report is found, whether it re-parses stale output, or how results are shaped.

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 that conveys the action and the prerequisite with no filler. Every clause earns its place.

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

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

With no output schema and no annotations beyond readOnlyHint, the description should describe what is returned (parsed issues, severities, counts) and clarify module/minSeverity behavior. None of that is present, leaving meaningful gaps for a 3-parameter tool.

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

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

Schema coverage is only 33% — projectDir is documented inline while module and minSeverity are not. The description adds nothing about what module selects or how minSeverity filters findings (default Warning), so it fails to compensate for the coverage gap; the enum values help but the filtering semantics remain unexplained.

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

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

States a specific verb (parse) and resource (Android Lint XML report), which distinguishes it from generic siblings like test_results or build. It is clear about what artifact it operates on, though it doesn't name a sibling it contrasts with.

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

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

Explicitly gives the precondition: run gradle_run with lintDebug or lint first, which tells the agent when this tool is applicable. It doesn't discuss alternatives (e.g., ide_problems) or what to do if the report is absent, so it falls short of a full when/when-not treatment.

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 say only readOnlyHint=false, so the agent has no explanation of why a 'Read' tool is flagged as mutating – the destructive 'clear' buffer behavior is never mentioned in the description even though it is the reason the read is not safe. It does add useful behavior for 'package' (resolves the current PID) and 'crashesOnly' (crash buffer, uncaught exceptions/ANRs), which is genuine context beyond the annotations.

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

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

Two short sentences, front-loaded with the core read action and then the filter options and the crash-buffer shortcut. Nothing is wasted, though it is dense enough that the destructive 'clear' path has no room.

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 says nothing about the return shape (raw log lines, ordering, whether truncation occurs at the 5000-line cap). With 8 optional parameters and a mutating flag, the definition is adequate but leaves an agent guessing about results and side effects.

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 88%, so the baseline is 3; the schema already describes tag, grep, clear, lines, serial, package, crashesOnly and minPriority. The description adds only two semantic nuggets (package uses the app's current PID, crashesOnly targets the crash buffer) and never mentions minPriority or serial handling.

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

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

States a specific verb and resource ('Read recent device logs') and enumerates the filter axes, so the agent knows exactly what this returns. It does not differentiate from the closest sibling (adb_shell), which could also surface log output, but the purpose itself is unambiguous.

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

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

The sentence 'Use crashesOnly to get the crash buffer' is real conditional guidance, and the filter list implies when each parameter applies. However, there is no 'when not to use this' direction, no pointer to adb_shell for non-log shell output, and no statement of prerequisites such as an online device.

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

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

The readOnlyHint annotation already establishes the safe-read profile, so the bar is lower. The description adds the meaningful behavioral detail that results are third-party only by default, but says nothing about output shape, pagination, or device-selection behavior when multiple devices are connected.

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

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

A single front-loaded sentence with no wasted words. It is perhaps too terse for the routing and device-selection context, but it is efficiently structured.

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

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

For a simple read-only, three-parameter tool this is minimally adequate. However, it omits important context around the serial parameter's conditional requirement and does not help an agent choose between this and related tools like project_apks or adb_shell.

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 moderate (67%), with filter and serial documented in the schema. The description adds meaning for thirdPartyOnly by clarifying its default behavior, which the schema only encodes as a bare default value.

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

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

States a specific verb and resource ('List installed packages') and adds a useful scope detail ('third-party only by default'). It does not name or distinguish itself from likely siblings such as project_apks or adb_shell, so it stops short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. An agent must infer that this is for enumerating installed packages rather than project APKs or shell queries.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully adds the newest-first ordering, but says nothing about whether all modules/variants are included, whether the list is paginated, or what happens when the project directory 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?

A single sentence with no waste, and the scope plus ordering are front-loaded. It is efficient, though the brevity contributes to the gaps elsewhere.

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 light read-only listing tool this is nearly sufficient, but with no output schema the agent has no idea what an entry looks like (path, variant, module name) and the 'module' filter is unaddressed, so the definition falls short of 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?

Only projectDir carries a schema description (50% coverage); the 'module' parameter is undocumented in both schema and description, and the description never mentions either parameter. With half the parameters unexplained, the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource — 'List APKs produced by previous builds' — plus an ordering guarantee ('newest first'). It is clearly distinguishable from the build-producing siblings, though it never names an alternative tool explicitly.

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

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

The phrase 'produced by previous builds' implies usage (you must have built first), but there is no explicit when-to-use, no exclusion, and no mention of what to do when no APKs exist. Guidance is inferred rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is only to add context. It does add that the call aggregates Gradle/AGP versions and module metadata, but says nothing about cost (whether it parses build files or queries a running IDE), what happens if projectDir is missing or invalid, or the shape of the result. Adequate but thin for an aggregation tool over 45 siblings.

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

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

A single sentence with the resource and its full contents front-loaded. No filler, no restatement of the title, and every listed field earns its place by signalling what comes back.

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 field enumeration usefully substitutes by telling the agent what the summary will contain. Combined with a single optional parameter and a read-only annotation, the definition is nearly self-sufficient; only the response format and failure behavior remain unspecified.

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

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

With one optional parameter at 100% schema coverage, the schema already documents projectDir and its ANDROID_PROJECT_DIR / cwd fallback. The description adds nothing about the parameter, which is acceptable at this coverage level but earns only the baseline.

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

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

Specific verb ("Summarize") plus resource ("the Android project") and an explicit enumeration of what the summary contains: modules, type, namespace/applicationId, SDK levels, launcher activities, Gradle/AGP versions. That enumeration distinguishes it from device_info, environment and project_apks by content. It never names a sibling or states the boundary explicitly, so it falls short of a 5.

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

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

No statement of when to call this versus alternatives (e.g. project_apks for APK artifacts, environment for toolchain paths, ide_project_problems/gradle_tasks for build state). The reader must infer the use case from the field list. No prerequisites, exclusions, or workflow placement are given.

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

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

With no annotations, the description carries the full burden; 'Runs as a job' is a valuable disclosure that the call is asynchronous and returns before completion. However, it does not say what the job handle looks like, that job_status must be polled, that it mutates device state, or what happens on build failure or when multiple devices are attached.

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

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

Two tight sentences, front-loaded with the conceptual anchor, zero filler. Every clause earns its place by naming the three concrete steps and the async execution model.

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 five-parameter, zero-required, no-annotation, no-output-schema tool, the description should at least say what comes back (a job identifier) and how to continue/poll. The 'Runs as a job' line gestures at this but leaves the return contract and multi-device selection behavior unexplained.

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

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

Schema coverage is 60%: serial, waitSec and projectDir are documented, but module and variant are bare. The description only obliquely touches 'variant' via 'assemble the variant' and says nothing about 'module', so it does not compensate for the two undocumented parameters and adds no format or defaulting 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 concrete composite verb chain (assemble → install → launch launcher activity) tied to a recognizable metaphor, the Android Studio 'Run' button. An agent can tell this is a one-step build+install+launch rather than any single sibling, though the description never explicitly contrasts with build/app_install/app_launch.

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

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

The 'Run button' framing implies when to use it (full end-to-end deploy), but there is no explicit guidance on when to prefer the granular siblings (build, app_install, app_launch) or on prerequisites such as a device being online or a synced project. Polling guidance lives only in the waitSec schema field.

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 `readOnlyHint: true` annotation already covers the safety profile. The description adds useful behavior by noting the screen is captured as PNG and can optionally be written to file, but it omits details such as device-online requirements or return format.

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

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

Two concise sentences, front-loaded with the core action and followed by the optional file-saving behavior. There is no redundant or 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 two-parameter read operation with full schema coverage and a `readOnlyHint`, the description is largely complete. It clearly states the output is a PNG and supports optional saving, though it could better differentiate from the sibling `ide_screenshot` tool.

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

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

Schema coverage is 100%, so the parameter meanings are already documented in the input schema. The description mentions the optional file-save behavior, which maps to `savePath`, but adds no syntax or format details beyond the schema.

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

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

The description states a clear verb and resource: capture the device screen as a PNG image, plus optional file saving. It is specific enough for an agent to understand the action, but it does not distinguish this from the sibling `ide_screenshot` tool.

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

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

There is no guidance on when to use this tool versus `ide_screenshot`, `ui_dump`, or other screen-related siblings. The only implied usage is the basic action itself, with no exclusions or 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 openWorldHint=true (downloads over the network) and destructiveHint=false, so the description only needs to add context. It usefully adds the Command-line Tools prerequisite, but omits license acceptance, download size/time, and whether install is additive vs replacing — meaningful for a mutating action.

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

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

One tight sentence: capability first, package-id examples second, prerequisite last. Nothing redundant and 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?

There is no output schema, so the description could say what list_installed/list_available return, and nothing explains multi-package install semantics for an array parameter. Prerequisite and example syntax are covered, but the definition is only adequate for a two-param, mutation-capable 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 0%, so the description must carry the burden. It does supply concrete package-id syntax ('platforms;android-36', 'system-images;android-36;google_apis;x86_64'), which is the key gap, but it never explains that 'action' selects the mode or that 'packages' is an array accepting multiple IDs.

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

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

States specific verbs (list installed/available, install) and the exact resource (SDK packages), and gives concrete package-id examples. An agent can tell this is SDK/command-line-tools package management rather than app installation, though it never names the siblings it is distinct from (packages_list, app_install, app_uninstall).

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

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

Usage is implied by the action enumeration, and one prerequisite is stated ('Requires the SDK Command-line Tools package'). However, there is no explicit guidance on when to choose this over packages_list or app_install, and no note on whether 'install' requires the list actions 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?

With no annotations, the description carries the full burden, and it does disclose one useful behavior: the running IDE window is reused if one is open. It does not say what happens when Studio isn't running, whether the call blocks until the IDE responds, or whether it fails for invalid paths — significant gaps for a tool that mutates the human's desktop state.

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 the window-reuse caveat in a parenthetical; no filler. The trailing usage note earns its place but is slightly buried after the behavioral detail.

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

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

No annotations, no output schema, and low parameter coverage mean the description needs to be more complete than it is: it omits what the call returns, what happens when Android Studio isn't already running, and how 'column' interacts with 'line'. Adequate for a simple hand-off action, but not fully specified.

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

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

Schema coverage is only 33% (only 'path' is documented), so the description must compensate. It does clarify that 'path' may be a project directory or a file and that 'line' positions within a file, but 'column' is undocumented in both schema and description, leaving one of three parameters opaque.

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 project, or a file at a line, in Android Studio'. That is concrete enough to act on, but it does not differentiate itself from the sibling 'ide_open', which sounds like it does nearly the same thing, so the agent cannot tell them apart from the description alone.

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

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

'Handy for handing off to the human' implies the usage context — surfacing a project/file in the human's IDE — but gives no explicit when-not conditions and never names 'ide_open' or 'ide_read_file' as alternatives. The agent must infer the split from the sibling list.

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

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

readOnlyHint=true already covers the safety profile, and the description usefully adds that it reads only the most recent run and requires a prior test execution. However it does not disclose the significant default behavior that failedOnly=true means only failures are shown unless overridden, nor what happens if the expected XML 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?

Two sentences, zero waste, with the core operation front-loaded and the prerequisite trailing. Nothing redundant.

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

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

With no output schema, the description should say more about what 'parse results' yields (per-test pass/fail, failure messages, counts) so an agent knows what it can rely on. It also leaves the failedOnly default's filtering effect unexplained. Adequate to select the tool, but thin for interpreting its output.

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

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

Schema coverage is 67%: module and projectDir are documented in-schema, while failedOnly carries only a default of true with no description. The description adds no parameter-level meaning at all, so the schema does essentially all the work; baseline 3 is appropriate for mid-range coverage.

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

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

States a specific verb ('Parse'), resource ('JUnit XML results'), and precise scope ('last unit test (test*UnitTest) or instrumented test (connected*AndroidTest) run'). The gradle task-name patterns make it unambiguous which artifact it reads, distinguishing it from siblings like gradle_run and lint_results.

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 prerequisite tool and ordering ('Run tests with gradle_run first'), which is the key usage condition. It does not state what to do when no results exist or when to prefer lint_results or ide_run instead, so it falls short of 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 readOnlyHint=true, so safety is covered; the description adds real context by disclosing the underlying uiautomator mechanism and that coordinates are directly usable for tapping. It omits practical traits of uiautomator dumps, such as the multi-second latency, which would have made it 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?

A single front-loaded sentence that packs the mechanism, the scope and the exact return structure with zero filler. Nothing to trim and nothing relevant buried later.

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 return-value disclosure and does so for the default mode (node list with named fields). It leaves the raw=true XML response undocumented, a minor gap for a simple three-optional-parameter read tool.

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

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

Schema description coverage is 100%, so the schema already explains raw, serial and includeAll; the description adds only marginal signal by describing the compact default form that raw=true overrides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (dump) and resource (on-screen view hierarchy) and goes further by naming the mechanism (uiautomator) and the output shape (compact node list with text, resource-id, content-desc, tap-ready centers). It does not explicitly contrast with the screenshot or adb_shell siblings, which is the only thing keeping it from a 5.

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

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

Usage is only implied: the phrase 'tap-ready center coordinates' hints this precedes an input/tap call, but there is no explicit when-to-use, when-not-to-use, or guidance on choosing this over screenshot or adb_shell for UI inspection. Baseline implied-usage score.

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