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

Annotations already declare destructiveHint=true, openWorldHint=true, readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that – it does not say which action destroys data (clear?), whether stop affects running state vs data, or what device targeting requires. It does not contradict 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?

A single front-loaded sentence with no filler; the action list leads. It is efficient, though arguably too terse for a 7-parameter destructive tool.

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

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

For a destructive, multi-parameter Android control tool with no output schema and 0% parameter coverage, the description is far too thin. An agent cannot know how to select a device, what activity/deepLink do, or what clear actually removes.

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 the burden, but it only loosely echoes the action enum values (start/stop/clear). Six parameters – serial, activity, deepLink, deviceId, deviceName, packageName – are undocumented in both schema and description, giving no guidance on device selection vs package targeting.

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 specific verbs (start, stop, clear) and a specific resource (Android package), so the function is unambiguous. However, it does not differentiate from close siblings like adb_install, adb_uninstall, or adb_packages, leaving the agent to infer when this tool is preferable.

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 reference to alternatives such as adb_install/adb_uninstall. The agent gets no signal about prerequisites (e.g., which action is reversible) or which sibling to prefer.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully discloses the returned metadata fields (state, model, product, transport), but says nothing about filtering behavior or how the optional params affect the result set.

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 efficient sentence that front-loads the action and resource. No filler, though it is arguably too short given the undocumented parameters.

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 list tool with annotations covering safety and no output schema, the definition is minimally adequate. However, the two undocumented filter parameters leave a real gap that the description should have closed.

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

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

Schema description coverage is 0% for two parameters (deviceId, deviceName), and the description never mentions them. The agent cannot tell whether these narrow the listing or what form they take, so the description fails to compensate for the schema 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 (List) and resource (ADB devices) and names the returned metadata fields. It distinguishes itself from the generic sibling list_devices via the ADB qualifier, though it doesn't explicitly contrast with the other adb_* tools.

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

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

No when-to-use, prerequisites, or alternatives are given. An agent must infer that this is a discovery step before adb_shell/adb_install/adb_pull, but nothing in the description states that.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the agent knows this is an unsafe, mutating, real-device action. The description adds only the tap mechanism (center of node), but does not disclose failure behavior (what happens if no match), multiple-match handling, or device targeting — useful context that annotations cannot supply.

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

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

A single, front-loaded sentence with zero filler; every clause earns its place and the core action and its differentiator are stated first.

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, 0%-coverage mutation tool with no output schema, the description is too thin: it omits device selection, match mode (exact/contains), index semantics for multiple matches, and result/failure reporting. An agent cannot reliably invoke it from this description alone.

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

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

Schema coverage is 0% and there are 9 parameters, so the description carries the full burden. It names only three matching criteria (text, resourceId, contentDesc) and leaves index, match mode, serial/deviceId/deviceName targeting, and requireClickable 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+resource ('Find an Android UI node ... and tap its center') and adds a differentiating rationale ('instead of guessing screen coordinates') that implicitly separates it from coordinate-based siblings like adb_input. It does not name the alternative tool, 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?

Usage is implied by the phrase 'instead of guessing screen coordinates', suggesting use when a target is identifiable by text/resourceId/contentDesc. However there is no explicit when-to-use/when-not guidance, no mention of adb_input or adb_ui_dump as alternatives, and no preconditions (device connected, UI settled).

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=true, so the safety profile is covered by structured data. The description adds no behavioral context beyond the operation list already present in the enum — it does not clarify device targeting, what 'destructive' means for a tap, or successful-injection side effects. With annotations carrying the load, the description's near-zero added value warrants a low score.

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

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

A single front-loaded sentence with no wasted words, which is good for structure. But for an 11-parameter, four-operation tool it is under-specified rather than genuinely concise, mirroring the calibration case where sparseness is penalized as under-specification.

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 multi-operation mutation tool with 11 conditional parameters and no output schema, the description leaves major gaps: which parameters select which operation, how the device is targeted (serial/deviceId/deviceName), and what a call returns. It is far short of complete enough for correct invocation.

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

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

Schema description coverage is 0% across 11 parameters, so the description carries the full burden — but it only echoes the four `type` enum values (tap, swipe, text, keyevent) without mapping which of x/y/x2/y2/text/keyCode/serial/deviceId/deviceName/durationMs apply to which operation. An agent gets no help resolving conditional or overlapping parameters.

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

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

The description names a specific verb (Send) and enumerates the resource/operations (tap, swipe, text, keyevent) plus the transport (adb). An agent can tell it does input injection rather than shell execution. However, it does not differentiate from siblings like adb_find_and_tap (which also taps) or adb_shell (which can run `input` too), 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 when-to-use guidance, no mention of prerequisites (a connected device/adb bridge), and no alternatives named. The agent must infer on its own that this is for direct coordinate-based input rather than element-targeted tapping via adb_find_and_tap.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds one piece of behavioral context — that the APK is read from the local workspace — but is silent on replace semantics, permission granting, and device selection.

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 with no filler and the key action front-loaded. It is efficiently written, though brevity here is partly the product of under-specification rather than deliberate editing.

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

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

For a 7-parameter mutation tool with no output schema and no annotation-level parameter help, the description is far too thin. An agent cannot tell how to pick among the device-identifier parameters or what replace/grantPermissions do.

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% across 7 parameters, so the description must carry the burden and does not. Only apkPath is obliquely referenced; the three overlapping device selectors (serial, deviceId, deviceName), replace, grantPermissions, and timeoutMs are 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 (Install) and resource (APK) and pins the source to the local workspace. It is clearly distinguishable from adb_uninstall, though it does not explicitly name siblings or what differentiates it from adb_push/adb_shell.

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

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

No when-to-use guidance, no prerequisites, and no mention of which device is targeted when multiple devices are attached. It never says when NOT to use it or which alternative (adb_push, adb_shell) applies 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?

Annotations already flag destructiveHint=true and openWorldHint=true, so the risk profile is covered. The description usefully adds that the process is persistent and returns a session handle for cursor reads, but says nothing about the effect of clearFirst on the device log buffer or session lifetime limits.

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

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

A single front-loaded sentence with no filler; the action and outcome come first. Slightly informal phrasing ("normal Raccoon process session") costs a point.

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

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

For a 6-parameter session-creating tool with no output schema and destructive annotations, the description should cover parameter behavior, session lifecycle, and cleanup; it covers none of these beyond stating that a session is returned.

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

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

Six parameters with 0% schema description coverage, and the description names none of them — filters, clearFirst, maxLogBytes, serial, deviceId are all unexplained, so an agent must guess formats and the destructive effect of clearFirst.

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

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

States a specific verb and resource ("Start persistent adb logcat") and clarifies the return artifact is a Raccoon process session used for cursor reads, which distinguishes it from one-shot sibling tools like adb_shell or process_read.

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

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

Implies usage via "persistent" and "for cursor reads" (stream/keep reading logs), but never states when to choose this over process_start/read_process_output or when to stop it (stop_search, kill_process). Only implicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: it does not say how the target device is chosen when serial/deviceId/deviceName are all omitted, nor whether the filter is a substring, regex, or package prefix match.

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 core action plus both filter axes are stated up front. It is efficient, though the brevity is partly what creates the documentation gaps.

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 tool with 0% schema coverage and no output schema, the description is too thin. Device selection semantics, filter matching behavior, and any notion of result ordering or size are all missing, so an agent cannot call it confidently beyond the happy path.

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% across five parameters, so the description must carry the load. It only loosely gestures at two of them (thirdPartyOnly via 'third-party', filter via 'text filtering') and says nothing about the three device-targeting parameters or their precedence, leaving the agent to guess.

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

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

States a specific verb (List) and resource (installed Android packages) plus the filtering dimensions, so it is immediately distinguishable from mutation siblings like adb_install/adb_uninstall. It does not explicitly differentiate itself from nearby read siblings such as adb_app or adb_devices, which keeps it below a 5.

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

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

The description never says when to pick this over adb_app, adb_devices, or adb_shell, nor does it state prerequisites such as needing a connected device or an active adb server. Usage is only implied by the word '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?

Annotations declare destructiveHint=true and readOnlyHint=false, so the agent knows a file lands on disk and something could be overwritten, but the description adds no behavioral context: it doesn't say whether the local path is overwritten, whether it requires an authorized device, or how timeouts/interruption behave. For a destructive 6-param tool, it should say more.

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

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

One short sentence, front-loaded with the action and resource, no filler. Appropriately sized even if under-informative; brevity is not the problem here.

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 destructive, open-world, six-parameter file-transfer tool with no output schema and no parameter coverage requires far more than one sentence. Nothing explains device targeting, overwrite semantics, or error/failure behavior, so an agent must guess.

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% across six parameters. The description mentions no parameter at all, leaving serial vs deviceId vs deviceName, remotePath/localPath, and timeoutMs fully undocumented and ambiguous (three seemingly redundant device selectors).

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 (pull) and resource (file from Android device) plus the destination (local workspace). It is clear what the tool does, but it never differentiates itself from adb_push, which is the inverse operation and the most common confusion point.

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 use this instead of adb_shell, adb_push, or adb_devices. With six parameters including serial/deviceId/deviceName, the description offers nothing on how to select a target device or when this tool is the right choice.

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, openWorldHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds only that the source is a local workspace file and the target is an Android device; it does not mention overwrite behavior, permissions, device selection, timeout behavior, or failure modes.

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 front-loaded sentence with no wasted words. It is appropriately concise structurally, even though it is incomplete in other dimensions.

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 six-parameter file-transfer tool with no output schema and zero schema description coverage, one sentence is not enough. Critical context such as overwrite semantics, device-target selection, and timeout behavior is absent.

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

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

Schema description coverage is 0% for six parameters, so the description must carry the explanatory burden. It only hints at localPath and the Android device target; it does not explain remotePath, serial, deviceId, deviceName, timeoutMs, or which device identifier should be used when multiple are supplied.

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: "Push a local workspace file to an Android device." It makes the transfer direction clear and implicitly distinguishes this from adb_pull, but it does not explicitly name or differentiate against sibling tools.

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

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

The description gives no guidance on when to use this tool versus adb_pull, adb_install, or other Android/file tools. It also does not explain device selection, prerequisites, or conditions where an alternative is preferable.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, but the description never explains what could be destroyed — a screenshot appears read-only, yet savePath implies writing/overwriting a file on disk, which is left unstated. The mechanism detail (adb exec-out, MCP image return) adds some value beyond annotations, but the destructive side effect is unexplained.

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, front-loaded with the action and return type, with no wasted words. It is structurally clean, though the brevity contributes to the missing parameter and usage guidance.

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

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

For a tool with five undocumented parameters, a destructiveHint=true annotation that is never elaborated, and no output schema, the description leaves an agent without enough to call it correctly or safely. Only the surface purpose is covered.

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?

Five parameters with 0% schema description coverage, and the description covers none of them. An agent gets no help on how to target a device (serial/deviceId/deviceName), what maxBytes bounds, or that savePath writes the image to disk.

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

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

States a specific verb and resource ('capture the current Android screen') and even names the mechanism ('adb exec-out'), plus the return medium ('MCP image'). It does not distinguish itself from close siblings such as screenshot_capture or android_app_snapshot, so an agent cannot tell from the text alone which screenshot tool to pick.

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

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

There is no statement of when to use this tool versus the many other capture/observation siblings (screenshot_capture, android_app_snapshot, adb_ui_dump, visual_compare). No prerequisites, no exclusions, no routing guidance at all.

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, openWorldHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds only the minor note that the target device is optional, and says nothing about the arbitrary-command risk surface, timeouts, or output truncation, so it is minimum-viable against the annotation bar.

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 efficient. The terseness is arguably under-specification rather than good concision, but structurally it is clean.

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 six-parameter tool with a defaulted timeout (120000 ms), an output byte cap, and three different device-identifier fields and no output schema, one sentence is insufficient. It leaves an agent unable to distinguish serial, deviceId, and deviceName or to understand output truncation behavior.

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

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

Schema description coverage is 0% across six parameters, so the description carries the burden and fails: 'optional target device' hints at serial/deviceId/deviceName but never disambiguates, and command, timeoutMs, and maxOutputBytes are entirely unexplained. The description does not 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 (Run) and resource (a command through adb shell), which is clear on its own. However, it does not differentiate itself from the sibling shell_run or the other adb_* tools, so an agent cannot tell from the description alone why it should pick this over shell_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 when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as shell_run or the more specific adb_install/adb_pull siblings. The agent gets no routing information beyond the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the output is a structured node tree with text, resourceId, content description, bounds, and interaction flags, which is useful. It omits caveats such as dump latency or device-targeting behavior, so it is adequate but not rich.

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

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

A single front-loaded sentence that states the command and the exact shape of the return value with zero filler. Every clause earns its place.

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

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

For a tool with four undocumented parameters, three of which appear to be redundant device selectors and one an output-format switch, the description is materially incomplete. It partially covers return values (helpful since there is no output schema) but says nothing about how to target a device or control includeXml.

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

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

Schema description coverage is 0% and all four parameters (serial, deviceId, deviceName, includeXml) are undocumented in the schema. The description mentions no parameters at all, so it completely fails to compensate for the coverage gap, leaving the agent to guess how to select a device or request raw XML.

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 ('Run uiautomator dump', 'Android UI tree') and enumerates the returned node fields, so an agent knows what the tool produces. It does not, however, distinguish this dump from the similarly oriented sibling 'android_app_snapshot' or 'adb_screenshot'.

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 only states what the tool does; it gives no when-to-use conditions, no alternatives comparison (e.g., adb_screenshot vs this for text extraction), and no prerequisites. Usage is only implied by the title and 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 destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive write. The description usefully adds that package data can be retained, which is real behavioral context beyond the annotations, but it never says what is actually removed, whether the uninstall is reversible, or what happens on failure.

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

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

A single front-loaded sentence with zero filler. The core action leads and the one behavioral caveat follows immediately.

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, multi-device tool with six undocumented parameters and no output schema, the description is too thin: it omits device selection semantics, timeout behavior, and failure/return expectations. Annotations cover the safety profile, but the invocation-relevant gaps remain.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the full burden and largely fails it. It alludes to the keepData option ('retaining its data') without naming it, and says nothing about serial, deviceId, deviceName, or timeoutMs, leaving device targeting and timeouts 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 ('Uninstall an Android package'), which clearly separates it from adb_install, adb_packages, and adb_app. It does not explicitly name or contrast a sibling tool, 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?

No when-to-use guidance, no prerequisites (e.g., whether the device must be connected/selected), and no alternatives named. The only conditional hint is 'optionally retaining its data', which is a capability note rather than usage guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds useful context by naming the returned state fields, but it does not explain device targeting behavior, crash-buffer retrieval limits, or any operational constraints.

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 return contents and scope without any 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?

With five parameters, 0% schema description coverage, and no output schema, the description is not complete enough. It names some returned fields but does not compensate for the missing parameter semantics or device-selection behavior.

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

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

Schema description coverage is 0%, and the description only vaguely implies packageName and crash-buffer state. It does not explain serial, deviceId, deviceName, packageName format, or the crashLines default and maximum, leaving most parameters undocumented.

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

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

States a specific verb and resource: return package version, PID, resumed activity, and crash-buffer state for one Android package. The scope is clear, though it does not explicitly distinguish itself from sibling tools such as adb_app or adb_packages.

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 snapshot versus alternatives like adb_app, adb_packages, or adb_shell. Usage is only implied by the word 'snapshot' and the returned fields.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds genuinely new behavioral content beyond that: the exact pipeline order, the startup wait, the UI-text assertion step, and the fact that an optional production package is checked for modification. It still omits what 'destructive' concretely means here (app overwrite/reinstall, data loss), permission/auth needs, and failure behavior for a 20-parameter mutating pipeline.

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 zero filler, and the clauses are ordered to match execution, so it reads as a pipeline rather than a word salad. It is a long grocery-list construction rather than structured prose, but no sentence is wasted.

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

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

For a 20-parameter, no-output-schema, destructive orchestration tool, the description is far too thin: it says nothing about what the pipeline returns on success, how partial failures (build ok / install ok / assertion fail) are surfaced, or which optional stages the many boolean/enum knobs toggle.

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% across 20 parameters, so the description carries the full burden and largely fails it. It only obliquely maps to a handful of inputs (buildCommand, apkPath, expectedTexts, crashLines, productionPackage), leaving cwd, runner, serial, deviceId/deviceName, activity, textMatch, grantPermissions, preserveProduction, all three timeout knobs, maxBuildOutputBytes and smoke completely 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?

The description names a specific, ordered sequence of verbs over one resource family (build → install APK → restart → wait → assert UI text → inspect crash → verify production package), which is far more than a tautology. It is clear what the tool does, but it never distinguishes itself from the many lower-level siblings (adb_install, adb_shell, adb_ui_dump, adb_app) it evidently orchestrates.

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 alternatives are named. The name 'cycle' plus the verb list implies it is the one-shot path over the granular adb_* tools, but the agent must infer that entirely; no conditions, prerequisites, or exclusions are stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the danger is covered. The description adds the useful scope fact that clearing can range from one key to the entire cache, but says nothing about permissions, irreversibility, or how deviceId/deviceName affect the target.

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 with the action front-loaded and no filler. It is efficient, though arguably too terse given the parameter and safety burden it must carry.

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 mutation tool with no output schema and 0% parameter coverage, the description is too thin. It omits what 'clear' actually destroys, the effect of omitting key, and the role of the device parameters, leaving an agent unable to invoke it confidently beyond the simplest case.

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% across 3 parameters, so the description carries the burden. It hints at the 'key' parameter ('one content-addressed build-cache key') and implies omission clears everything, but deviceId and deviceName are entirely unexplained in both schema and description.

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

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

States a specific verb (clear) and resource (build cache) with two clear scopes: a single content-addressed key or the entire cache. It is naturally distinguishable from siblings build_cache_run and build_cache_stats, though it doesn't name them explicitly.

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

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

No guidance on when to clear a single key versus the whole cache, no prerequisites, and no reference to alternative tools. The two modes are mentioned but the selection criteria between them is left entirely to inference.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, so the agent already knows this runs something with side effects. The description adds genuinely useful cache semantics (hash-based key, restore-on-hit, write-on-miss), which goes beyond the annotations, but it never states what 'restore cached outputs' overwrites, what happens on a failed run, or that an arbitrary command is executed with disk writes.

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 mechanism and walks through hit and miss paths. No filler, no redundancy.

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

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

For an 11-parameter, destructive, open-world build runner with no output schema and 0% parameter documentation, the description is too thin. It does not explain parameter behavior, cache-key composition beyond 'declared inputs', failure handling, or what a caller should expect to get back.

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% across 11 parameters, and the description only alludes to three of them (command, inputs, outputs). Key controls like force, restore, cwd, environment, timeoutMs, maxOutputBytes, deviceId and deviceName are undocumented in both schema and description, leaving most of the surface 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?

The description states a specific mechanism with concrete verbs and resources: hash inputs+command, restore outputs on hit, run and cache on miss. An agent can immediately tell this is a cached build runner. It does not, however, explicitly differentiate itself from near-siblings like build_cache_clear, build_cache_stats, or project_build_test.

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

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

There is no explicit when-to-use guidance, no mention of when a cache hit vs miss matters to the caller, and no routing to alternatives such as build_cache_clear or shell_run. Usage is only implied by the description of the hit/miss mechanics.

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 destructiveHint=false, so the safety profile is covered by structured data. The description adds what data is surfaced (entries, hit counts, disk usage), which is useful, but says nothing about filtering by device, scoping, or result volume.

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 names the verb and the exact data returned with zero filler. Every word earns its place.

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

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

For a simple read-only stats tool with no output schema, naming the returned data is largely sufficient. However, the unexplained deviceId/deviceName parameters and the absence of any device-scoping statement leave a real gap for correct invocation.

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

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

Schema description coverage is 0% and the two parameters (deviceId, deviceName) are entirely undocumented in both schema and description. The description mentions no parameters at all, so it does not compensate for the coverage gap; an agent cannot tell whether these are filters or required identifiers.

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

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

States a specific verb (list) and resource (build-cache entries, hit counts, disk usage), so an agent can immediately tell what the tool returns. It does not explicitly contrast itself with siblings like build_cache_clear or build_cache_run, 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?

There is no guidance on when to use this versus the closely related build_cache_clear and build_cache_run tools, nor any prerequisites mentioned. The agent must infer the context from the name alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, so the risk profile is covered. The description adds genuine pipeline context the annotations cannot convey: it waits on a version/deployment condition, captures values, conditionally activates traffic with those values, and performs 'secret-aware' assertions (matching the secretRef schema). However it omits what gets destroyed, whether activation is irreversible, and how failures mid-pipeline are handled.

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 walks the pipeline in execution order with no filler or repetition. It is efficient, though the comma-chained clauses make it dense for a tool with this much surface area.

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 12-parameter, deeply nested orchestration tool with no output schema and no annotation detail, one sentence is insufficient. It omits failure/rollback behavior, what captured values are and how they feed activation, and how secret references are resolved – all of which an agent needs before invoking a destructive, open-world pipeline.

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% across 12 parameters with heavy nesting, so the description carries the full burden. It loosely gestures at deployCommand, versionProbe/capture, activateCommand, and probes/assertions, but leaves cwd, runner, deviceId, deviceName, all timeouts, and maxOutputBytes unexplained, and adds no format or meaning beyond parameter names.

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 concrete verb sequence (run deploy → wait for version condition → capture → activate → assert) on a named resource (Cloudflare deployment), so the composite purpose is clear. It does not explicitly contrast with siblings like http_probe, wait_until, shell_run, or dev_pipeline_start, which all overlap with sub-steps of this workflow, so sibling differentiation is missing.

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 statement of when to use this orchestrated tool versus the individual siblings that do the same steps (shell_run for the deploy command, http_probe for assertions, wait_until for condition polling). Usage is only implied by the step list; no prerequisites, preconditions, or exclusions are given.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The word 'recursively' adds real behavioral context (whole subtree is copied), but the description omits critical traits: whether an existing destination is overwritten, whether it fails or merges, and permission requirements.

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

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

A single front-loaded sentence with no filler. It is efficient, though arguably underspecified rather than optimally concise for a destructive mutation 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?

No output schema, no parameter documentation, and only an annotation-level safety signal. For a destructive recursive copy with device-targeting parameters, an agent still lacks overwrite semantics, failure behavior, and any parameter meaning.

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

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

Schema coverage is 0% and the description adds nothing about the four parameters. Two non-obvious fields (deviceId, deviceName) are left completely unexplained as to what they target or whether they are optional. It does not 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 (copy) and resource (file or directory) plus the recursive scope, which distinguishes it from a shallow single-file copy. It does not explicitly name siblings like move_file or delete_path, but the copy verb naturally separates it from those.

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 use this versus move_file, fs_write_* alternatives, or device-targeted transfer tools (adb_push). Nothing about prerequisites, destination existence, or overwrite conditions is stated.

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

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

Annotations already declare `readOnlyHint=false`, `destructiveHint=true`, and `openWorldHint=false`, so the agent knows this is a mutating, potentially destructive operation. The description adds one behavioral detail—that creation is recursive—but does not explain what gets destroyed, whether existing directories are overwritten, or what permissions are required, leaving meaningful gaps.

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

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

The description is a single, tightly worded sentence with the verb front-loaded and zero filler. It contains no redundant or vague phrasing.

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 mutating tool with three parameters (one required, two optional), no output schema, and no schema descriptions, the description is far too sparse. It omits parameter semantics, error behavior, and any elaboration on the `destructiveHint` annotation, leaving the agent under-informed about how 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 0% for three parameters (`path`, `deviceId`, `deviceName`), and the description adds no meaning to any of them. It does not clarify the expected path format, whether `path` is absolute or relative, or what the optional device parameters are for.

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 ('Create') and resource ('directory'), making the tool's basic purpose immediately clear. It does not, however, distinguish itself from sibling tools or clarify scope beyond the word 'recursively'.

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 like `list_directory`, `write_file`, or other filesystem operations. The adverb 'recursively' hints at a condition (creating parent directories) but does not constitute usage guidance or exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, and the description's 'mutating' is consistent with them. It adds the parameterized-statement capability but says nothing about transaction semantics, what data can be destroyed, permission requirements, or error behavior for a destructive open-world 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 front-loaded sentence with no filler or redundancy. It is efficient, though its brevity borders on under-specification for a five-parameter destructive 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?

A destructive mutation with five undocumented parameters and no output schema warrants more than one clause. Nothing tells the agent which database file is targeted, how params binds, or what a successful execution returns.

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% with five parameters, so the description carries the full burden. 'Parameterized statement' hints at the params field but file, deviceId, and deviceName are left entirely undefined in both schema and prose.

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

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

States a specific verb (Execute) plus resource (SQLite SQL / parameterized statement), and the word 'mutating' carves out the write side. It does not name the sibling it is distinct from, so an agent must infer the split against db_query_start on its own.

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 'mutating' implies this is for writes rather than reads, which is a weak but real usage signal. There is no explicit when/when-not and no reference to db_query_start/db_query_next/db_info as the read-path alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns schema plus page/database metadata, but says nothing about permissions, the file being opened read-only, or failure modes. With annotations carrying the safety bar, a 3 is appropriate.

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 with no filler, front-loaded on the verb and resource. Nothing wastes space.

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

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

For a simple read-only inspection tool with full annotation coverage and no output schema, the description is broadly adequate, but it leaves the file/deviceId/deviceName parameters entirely unexplained, which is a notable gap for invocation correctness.

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

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

Schema coverage is 0% and the description explains none of the three parameters. It never clarifies what "file" points to (a path? on which device?) or what deviceId/deviceName are for, leaving a real ambiguity an agent must guess 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 ("Inspect") and resource ("SQLite schema and basic page/database metadata"), which clearly distinguishes it from query-execution siblings like db_execute and db_query_start. It does not explicitly name those alternatives, but the read-only inspection framing 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 when-to-use guidance, no prerequisites, and no routing to alternatives such as db_execute or db_query_start. The agent is left to infer that this is the read-only structural-inspection tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope by saying both the session and the database handle are released, but omits idempotency, error behavior for an unknown/expired sessionId, and whether other sessions are affected. Note the mild tension between 'Close' (a state change) and readOnlyHint=true, though this is resource cleanup rather than data mutation, so it is not a true contradiction.

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. Every word carries information about the operation and its targets.

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 lifecycle/cleanup tool with no output schema and zero parameter documentation, the description is too thin: it never explains the session lifecycle, the role of the optional device parameters, or failure modes. An agent can guess the call but not call it confidently in edge cases.

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% across three parameters. The word 'session' loosely implies sessionId, but deviceId and deviceName are entirely undocumented in both schema and description, and nothing explains how the three relate or which must be supplied. The description does not 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 (Close) and resource (retained SQLite query session and database handle), which is clearly distinguishable from the db_query_start/db_query_next/db_query_sessions siblings in the same family. It stops short of naming the sibling that creates the session it closes, so differentiation is implied rather than explicit.

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

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

No when-to-use guidance: it does not say to call this after db_query_next is exhausted, whether closing is mandatory for cleanup, or what happens if the session is still active. The agent must infer the lifecycle role from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The phrase 'retained streaming query iterator' usefully signals server-side session state that persists across calls, but the description does not disclose drain/termination behavior or lifecycle coupling to db_query_close.

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 with the key qualifiers ('next', 'retained', 'streaming') front-loaded. It is not padded, though it is arguably too terse for a 4-parameter stateful tool.

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

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

For a stateful iteration tool with no output schema and 0% schema description coverage, the description leaves critical gaps: how batches are bounded, how completion is signaled, and how the sessionId relates to db_query_start/db_query_close. Annotations cover only the safety profile, not the iteration contract.

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

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

Schema description coverage is 0% across 4 parameters, so the description must carry the load, and it adds nothing: sessionId's required-ness and origin, maxRows' default of 500 and max of 100000, and the deviceId/deviceName roles are all unexplained. An agent must guess that sessionId comes from db_query_start.

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 (next rows from a retained SQLite streaming query iterator), which clearly distinguishes it from db_query_start, db_query_sessions, and db_query_close among the siblings. It does not explicitly name which sibling precedes it, but the 'next' framing makes the pagination role inferable.

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 never says when to call this versus db_query_start, db_query_close, or db_execute, nor that a prior db_query_start session must exist. Nothing states termination conditions or what to do when the iterator is exhausted.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that only currently retained streaming sessions are returned, which is useful context, but says nothing about return format, pagination, or how sessions become retained.

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 fits a simple list operation. It is efficient, though its brevity contributes to the missing usage and parameter context.

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 two undocumented optional filter parameters, no output schema, and closely related siblings (db_query_start/next/close, list_sessions), the definition leaves key gaps: what 'retained' means, whether filters are required together, and when this tool belongs in a query workflow.

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

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

Schema description coverage is 0% and the description is completely silent on deviceId and deviceName, so the agent gets no hint that these are optional filters or how they interact. This fails to compensate for the missing schema documentation.

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

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

States a specific verb (List) and resource (SQLite streaming query sessions), and 'currently retained' narrows scope. It is clearer than the generic sibling list_sessions, but does not explicitly distinguish itself from db_query_start/db_query_next/db_query_close or explain what a retained session is.

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

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

No when-to-use guidance, no alternatives, and no condition telling the agent to prefer this over list_sessions or the other db_query_* tools. 'Currently retained' implies a context but does not instruct.

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

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

Annotations already declare the operation as read-only, non-destructive, and closed-world. The description adds meaningful behavioral context beyond that: it returns only the first batch and retains an iterator for later batches, which is a non-obvious side effect. It still omits iterator cleanup and error behavior, but the added disclosure is strong for a single sentence.

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 one front-loaded sentence with no filler. Every phrase adds information: query preparation, first-batch return, and iterator retention.

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, 0% schema description coverage, and 7 parameters, the description is insufficient for correct invocation. It covers the core streaming purpose but omits parameter semantics, follow-up batch mechanics, and when to use this versus sibling query tools.

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

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

The schema has 0% description coverage across 7 parameters, so the description carries the full burden of explaining parameter meaning. It says nothing about sql, file, params, deviceId, readOnly, batchRows, or deviceName, leaving them documented only by name and type.

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

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

The description states a specific verb and resource: prepare a SQLite query, return the first batch, and retain the iterator. This clearly distinguishes it from a simple execute tool and implies a streaming workflow, though it does not explicitly name db_query_next or db_query_close as the follow-up tools.

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

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

The description implies usage context by mentioning 'first batch' and 'subsequent batches,' so an agent can infer this is for streaming/paginated queries. However, it gives no explicit when-to-use guidance versus db_execute, db_query_next, or db_query_close.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered externally. The description adds only the word 'recursively', and that claim is misleading since the schema exposes a `recursive` boolean defaulting to false, implying recursion is opt-in rather than automatic. No mention of permanence, protection, or auth needs.

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

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

A single short sentence that is front-loaded and wastes no words. However, the brevity reflects under-specification rather than tightness, leaving the most important details unstated.

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 no output schema and no annotation-level guidance on irreversibility or permissions, the description is far too thin. An agent cannot determine device scoping or that recursion is optional from the text alone.

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

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

Schema description coverage is 0% for 4 parameters (path, deviceId, recursive, deviceName). The description touches on the file/directory distinction and recursion but does not document deviceId, deviceName, or the optional nature of `recursive`, so it 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 (delete) and resource (file or directory) with a scope qualifier (recursively). It is clearly distinguishable as the destructive-delete operation, though it does not name or contrast with any sibling 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 indication of when to use this tool versus alternatives such as fs_write_text, move_file, or copy_file, nor any prerequisites or cautions about when not to use it. The agent must 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?

Adds substantial behavior beyond the annotations: auto foreground-control acquisition, a visible AI-control overlay for the whole batch, continuous heartbeat, and automatic lease release on completion. These lifecycle traits are genuinely extra context the destructiveHint/openWorldHint flags don't convey.

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

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

Three front-loaded sentences: purpose first, then lifecycle guarantees, then the conditional leaseId rule. No filler or redundancy.

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

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

No output schema, so the agent relies on the description for return behavior, which it partly covers via the batch lifecycle (overlay, lease release). Combined with annotations carrying the safety profile, it is mostly complete, though the action variants and the meaning of task/ttlMs remain unaddressed.

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

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

Schema description coverage is 0% across 7 params, and the description only clarifies leaseId semantics. The core 'actions' structure, task, owner, ttlMs, deviceId and deviceName are left entirely to schema inference, so it adds meaning for only one 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 (Run) and resource (a batch of Windows mouse, keyboard, scroll, wait and window-activation actions), enumerating the action categories the tool covers. This is enough to distinguish it from the foreground_control_* and adb_input siblings without opening the schema.

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

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

The description implicitly routes the agent away from foreground_control_acquire by stating control is acquired automatically, and gives an explicit condition for leaseId ('only when intentionally joining a manually acquired foreground-control session'). It does not explicitly state when-not to use it or contrast with Android/process-injection siblings, keeping it below a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral scope beyond that: it lists only *visible top-level* windows, names the returned fields, and explicitly disclaims foreground control. It does not cover enumeration limits, ordering, or failure modes, so it falls short of a 5.

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

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

Two short sentences with the core verb and resource front-loaded, and no filler. The second sentence is a useful constraint rather than padding, though it could have been folded into the first for tighter structure.

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

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

No output schema exists, and the description does disclose the return shape (title, PID, handle), so return-value burden is met. What is missing is any guidance on the two parameters, a minor but real gap for a tool with 0% schema coverage.

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

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

Schema description coverage is 0% and the description says nothing about deviceId or deviceName. With two undocumented parameters, the description does not compensate for the gap; an agent cannot tell whether deviceId scopes the enumeration to a remote device or is optional/ignored when omitted.

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 visible top-level Windows windows' plus the returned fields (title, process ID, native handle). It also carves itself away from the foreground-control family, though it stops short of naming a specific sibling tool. Clear and actionable, but sibling differentiation is indirect.

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

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

The clause 'does not claim foreground control' implies this is a passive inspection tool and hints that foreground_control_acquire is the alternative for control, but no explicit when-to-use or alternative is named. Usage is only implied, leaving the agent to infer the routing.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it clarifies the scope ('owned process trees') and warns that 'Already-started external side effects are not automatically rolled back' and that active nodes settle asynchronously.

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, front-loaded sentences that each carry distinct information: the action, the rollback caveat, and the settling behavior. No filler.

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

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

For a destructive mutation with annotations covering safety, the description discloses the key non-obvious traits (no rollback, eventual settling). However, with 0% schema coverage and no output schema, the parameters remain entirely undocumented, which is a notable gap for a 4-param 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% across 4 parameters (runId, deviceId, deviceName, confirmInterrupted), yet the description explains none of them. It doesn't clarify what runId identifies, when deviceId/deviceName are needed, or what confirmInterrupted gates — leaving the entire param surface 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+resource: 'Cancel queued nodes and terminate owned process trees.' Clear within the dev_pipeline family that this is the cancellation tool. It doesn't explicitly contrast with sibling alternatives like force_terminate or dev_pipeline_wait, so sibling differentiation is only 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?

'Poll state until active nodes settle' gives an implied follow-up workflow (poll dev_pipeline_status), but the description never states when to use this vs dev_pipeline_wait or force_terminate, nor any preconditions for cancellation.

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, destructiveHint=false, and a closed world, so the safety profile is covered. The description adds one real behavioral fact beyond the annotations – ordering is newest-first – but says nothing about pagination, how many runs exist, or what a 'persistent' run is.

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

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

A single compact sentence with the ordering constraint front-loaded and no wasted words. Efficient, though the brevity is partly achieved by omitting needed content rather than by tight editing.

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 list tool with no output schema, the description carries no information about filtering parameters, result shape, or default limits despite three undocumented parameters. An agent has to guess how deviceId/deviceName narrow 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?

Schema description coverage is 0% for three parameters (limit, deviceId, deviceName), and the description mentions none of them. It does not explain that results can be scoped by device or capped by limit, so it fails to compensate for the documentation 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?

Clear verb+resource: 'List persistent pipeline runs.' An agent can distinguish this from dev_pipeline_status (single run) and dev_pipeline_logs without opening a schema. However, 'persistent' is ambiguous and no sibling is named explicitly, 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 statement of when to use this versus dev_pipeline_status, dev_pipeline_logs, or dev_pipeline_wait, nor any prerequisites. Usage context is left entirely to inference from the name.

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

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

Annotations already declare a safe read profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description still adds real value beyond them: logs may contain command output and there is no automatic secret scrubbing, a genuine security-relevant disclosure an agent should act on.

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 core action front-loaded and the safety caveat second. 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 7-parameter tool with no schema descriptions and no output schema, the definition is too thin. It does not explain how logs are keyed, how to page via offset/maxBytes, or the relationship of attempt and device parameters, so an agent cannot call it precisely.

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 7 parameters with 0% schema description coverage, so the description carries the full burden and falls short. It never explains runId/nodeId selection, or the offset/attempt/maxBytes/deviceId/deviceName parameters, leaving pagination and device targeting entirely 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 (Read) and resource (bounded persisted node logs) with meaningful scope words 'bounded' and 'persisted'. It is distinguishable from siblings like dev_pipeline_status or read_process_output, though it does not explicitly name the pipeline family or contrast with them.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer from the resource noun alone that this retrieves logs for a pipeline node rather than live process output or pipeline status.

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

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

Adds real context beyond the annotations: non-selected completed results are preserved, interrupted runs require a reconciliation gate before confirmInterrupted=true, and commands are immutable across resume. With destructiveHint=true already declared, it usefully clarifies blast radius, though it doesn't state what happens to failed (non-completed) nodes.

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, with the core retry semantics front-loaded and the reconciliation caveat and command-immutability follow-up each earning their place.

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

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

For a 5-param mutation tool with no output schema, the description covers the nontrivial resume semantics and the confirmInterrupted gate well. It is not fully complete because device/run identifier parameters are undocumented anywhere.

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

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

Schema coverage is 0%, so the schema documents nothing and the description must carry the load. It gives meaning to nodes ('selected nodes and their descendants') and indirectly to confirmInterrupted, but leaves runId, deviceId, and deviceName completely 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 (retry/resume) and resource (selected pipeline nodes and descendants) with the key scoping constraint of preserving other completed results. It is clearly distinct from dev_pipeline_start via the 'submit a new graph' note, though it never names the 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?

Gives a concrete when-condition ('Interrupted executions require reconciliation before confirmInterrupted=true') and routes the change-command case to a new graph instead of this tool. It stops short of an explicit when-not/alternatives sentence naming dev_pipeline_start or dev_pipeline_cancel.

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 the safety profile (not read-only, open-world, destructive); the description adds genuinely useful behavior beyond them: the call returns immediately (async), the DAG persists in the background, lock names coordinate shared resources, and retries are only safe for idempotent nodes. It still does not explain what the destructive aspect is or how results are later retrieved.

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

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

Four short sentences, each carrying a distinct operational fact, with the core behavior ('Returns immediately') front-loaded. No filler.

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

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

For a tool with a large nested schema, no output schema, and 0% parameter documentation, the description is far too thin: it omits how to observe the run (dev_pipeline_status/logs/wait), what the returned handle is, and most node configuration semantics. The runtime behavior notes help but do not cover the calling surface.

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% across a 4-parameter schema with a deeply nested pipeline object (nodes with dependsOn, retries, timeoutMs, capture, retryUntil, etc.). The description only touches node 'locks' and node 'idempotent'; deviceId, deviceName, idempotencyKey, pipeline.name, cwd, parallelism and the bulk of node fields are 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 and resource ('Start a persistent background DAG') that an agent can distinguish from validate/status/list/wait siblings. It does not, however, differentiate itself from dev_pipeline_resume or process_start, which also launch work.

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

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

Usage is implied rather than stated: 'persistent background DAG' hints this is for fire-and-forget orchestration, and the lock/idempotency notes give modeling guidance. There is no explicit 'use this instead of X' or precondition statement against the many sibling pipeline tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that result tails are 'bounded' (i.e., truncated output), but says nothing about permissions, latency, or pagination behavior.

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

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

A single front-loaded sentence with no filler. It is efficient, though bordering on under-specification rather than genuinely tight.

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

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

For a tool taking a required run identifier plus device scoping, the description never explains what the parameters select or what a caller should expect to receive. No output schema exists, so the description should carry more of this burden than it does.

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% across three parameters, and the description adds no meaning for runId, deviceId, or deviceName. With a required UUID runId and two undocumented optional device parameters, the description fails to compensate for the schema gap at all.

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

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

The description states a specific verb (Read) and resource (pipeline state) plus what it surfaces (result tails, artifact paths), which is clearer than a bare name restatement. However, it does not distinguish itself from close siblings like dev_pipeline_logs, dev_pipeline_wait, or dev_pipeline_list, so an agent cannot confidently route between them from the text alone.

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

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

There is no when-to-use guidance, no preconditions, and no named alternative. With six sibling dev_pipeline_* tools sharing this namespace, the absence of any routing signal is a meaningful gap.

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 destructiveHint=false, and the description corroborates this by promising no execution. It goes further to enumerate the constructs it validates (variable capture, conditions, retryUntil polling, locks, explicit runners), giving the agent a real sense of validation scope.

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 non-execution qualifier appears at the end where it lands with impact. Dense but not 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 tool validating a 256-node DAG schema with many nested options and no output schema, the description omits what a validation result contains (error list, schema violations) and how failures are reported. Adequate but leaves meaningful gaps.

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

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

With 0% schema description coverage on a deeply nested pipeline object, the description must carry the burden. Its feature list (capture, conditions, retryUntil, locks, runners) loosely maps to nested fields but gives no syntax, constraints, or guidance on the deviceId/deviceName parameters.

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

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

States a specific verb (validate) and resource (persistent task DAG) and adds the crucial scope qualifier 'without executing it.' This implicitly separates it from execution siblings like dev_pipeline_start, though it never names an alternative 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 'without executing it' implies this is a dry-run/pre-flight check, but the description never states when to prefer it over dev_pipeline_start or what a passing/failing result should trigger. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful non-annotation context: the 30s ceiling and, crucially, that 'tasks continue if this request disconnects' — a server-side async behavior an agent cannot infer from structured fields.

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

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

Two efficient clauses with the behavioral payoff (wait scope, revision hint, disconnect safety) front-loaded and no filler. Slightly compressed to the point of omitting needed detail, but structurally sound.

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

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

With no output schema, 5 params at 0% coverage, and a timing-sensitive tool, the description should clarify what is returned on timeout vs. completion and the role of the device params. It conveys the wait semantics well but leaves the parameter surface and timeout outcome underspecified.

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, but it only addresses two of five params indirectly (the '30s' cap maps to waitMs, 'last revision' maps to afterRevision). runId, deviceId, and deviceName are left entirely unexplained in both schema and prose.

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

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

States a specific verb+resource ('wait' on a dev pipeline revision/completion) and its scoping behavior ('up to 30s'). An agent can tell it is a long-poll wait tool, but the description never names the sibling it complements (dev_pipeline_status) or contrasts with wait_until, so sibling differentiation is left to inference.

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

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

It gives conditional guidance for one parameter ('supply last revision to avoid polling unchanged state'), which implies usage, but never states when to prefer this over dev_pipeline_status or wait_until, nor any prerequisites for calling it. Usage is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write/mutation nature is covered structurally. The description adds almost nothing beyond that: it does not say matches must be exact and unique, what happens when old_string is missing or ambiguous, how expected_replacements guards against unintended edits, or how DOCX/Excel edits alter the underlying file. For a destructive multi-mode editor this is a significant 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 tight sentence with no filler, and the three modes are front-loaded so an agent can scan it quickly. It is terse rather than padded, though the brevity reflects under-specification rather than disciplined economy.

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

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

For an 8-parameter, destructive, multi-format edit tool with 0% schema documentation and no output schema, one sentence is not enough. An agent cannot reliably determine mode selection, required companion parameters, or failure behavior from what is provided.

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

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

Schema description coverage is 0% for 8 parameters, so the description carries the full burden and largely fails. It hints that old_string/new_string/expected_replacements drive text replacement and that range/content drive Excel updates, but it never explains how parameters map to modes, what 'content' accepts, or the role of deviceId/deviceName. Only partial compensation for the coverage gap.

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

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

The description names a specific verb ('edit') and enumerates three distinct operation modes (exact text replacement, DOCX XML replacement, Excel range update), which tells an agent what the tool can do. However, it offers no differentiation from closely related siblings such as fs_write_text, fs_apply_patch_many, or write_file, leaving mode selection ambiguous.

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 choose this tool over the many file-mutation siblings, nor any prerequisites, exclusions, or guidance on which of the three modes applies to which file type. An agent must infer everything from the one-sentence mode 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful scoping fact that the target is a Raccoon-managed persistent process, but it does not explain what 'force' means (SIGKILL vs. graceful signal), whether buffered output is lost, or whether the process must be currently running.

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

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

A single front-loaded sentence with zero filler and no redundant restatement of the title. Its terseness is arguably the flaw, but it is not padded or poorly 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 destructive, 3-parameter mutation tool with 0% schema coverage, no output schema, and multiple competing kill/stop siblings, the description is too thin. It omits force-vs-graceful semantics, required process identity beyond a bare pid, and any indication of failure modes when the pid is not Raccoon-managed.

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% across 3 parameters, so the description carries the full burden and does not compensate: it never mentions pid, deviceId, or deviceName, nor how to disambiguate a process on one device versus another. It only implies that some process identifier is the target.

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 (Terminate) and resource (persistent process) and narrows the scope with 'started through Raccoon', which implicitly separates it from generic OS-level killers. However, the sibling set contains kill_process, process_kill, and stop_search, and the description never explicitly contrasts itself with them, so an agent must infer the difference.

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

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

There is no when-to-use guidance at all, despite several overlapping termination/stop siblings (kill_process, process_kill, stop_search). Nothing states the precondition that the process must be one tracked by Raccoon, nor when force termination is preferable to a graceful stop.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds genuinely useful context beyond them: a topmost Windows overlay is created and the hold is lease-based, ending on release or heartbeat expiry. It still omits the critical conflict case (what happens if the foreground is already held) and any permission/error behavior.

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

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

A single front-loaded sentence that states purpose and termination condition with no filler. Efficient, though for a 5-parameter lease tool the brevity borders on under-specification rather than being purely a strength.

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 5-parameter, zero-coverage, no-output-schema tool, the description leaves major gaps: parameter meanings, conflict/preemption behavior, and acquisition failure modes are all unstated. Annotations carry the safety profile, but the functional contract is thin.

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

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

Schema coverage is 0% across 5 parameters. The description clarifies none of them – task, owner, deviceId, deviceName are unexplained, and ttlMs is only obliquely implied by 'heartbeat expiry' with no units, bounds, or default noted. The description does little 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 (reserve/acquire) and resource (the human-interaction foreground) plus the visible effect (topmost Windows overlay), so the agent knows exactly what this does. It is clearly the 'acquire' member of the foreground_control_* family, though it never names those siblings to sharpen 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?

No explicit when-to-use, preconditions, or alternatives are given. The lifecycle phrase 'until released or heartbeat expiry' hints that release/heartbeat must follow, but the agent must infer that from the sibling names rather than from any stated guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds useful context that the task update is optional (overlay content changes only when 'task' is supplied), but it never explains why the operation is flagged destructive or what state is lost on expiry.

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 primary action first and the optional side effect clearly marked. No waste, though it is arguably too terse for a mutation tool.

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

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

For a mutating lease tool with four undocumented parameters, no output schema, and a surprising destructiveHint=true, the description omits lease lifetime/failure semantics, device parameter meaning, and any indication of required permissions.

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

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

Schema coverage is 0%, so the description carries the burden and only partially compensates: it implies the 'leaseId' renewal and the 'task' overlay text, but says nothing about 'deviceId' or 'deviceName', leaving two of four parameters undocumented 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 ('Renew') and resource ('foreground-control lease'), plus the optional secondary effect on the overlay task. This clearly separates it from foreground_control_acquire/release/pause, though it does not name those siblings explicitly.

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

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

No when-to-use guidance, no mention of the sibling tools, and nothing about the heartbeat cadence, lease expiry window, or what happens if the lease has already lapsed. The agent is left to infer that this is a periodic keep-alive call.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the risk profile is partly covered. The description adds genuinely new behavioral context — that pausing suppresses GUI input — but says nothing about reversibility, whether the lease must be held first, or effect on device scoping. Modest added value over 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 action and followed by the operative effect. No filler, though the extreme brevity leaves little structure to speak of.

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, four-parameter lease-manipulation tool with 0% schema coverage and no output schema, the description does not supply enough to call it safely. It omits how the lease is identified, how device scoping works, and what state results from the toggle.

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% across four parameters, so the description carries the full burden and fails it. It never explains leaseId (required), paused (default true), or the deviceId/deviceName scoping pair; only the words "pause or resume" loosely imply the paused flag.

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

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

States a specific verb pair (pause/resume) and a specific resource (the active AI foreground-control lease), which cleanly separates it from acquire/heartbeat/release/status siblings by name. It doesn't explicitly name those alternatives, but the operation is identifiable without reading the schema.

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

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

Offers a consequence ("GUI automation should refuse input while paused") but no guidance on when to pause versus release or heartbeat the lease, and no prerequisites. Choosing between this and foreground_control_release is left entirely to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, lowering the disclosure bar. The description adds a useful user-visible side effect ('dismiss the Windows overlay'), but does not say whether the lease is invalidated, whether an unacquired/stale leaseId errors, or whether the operation is idempotent.

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 with the verb front-loaded and no filler. Nothing is wasted, though this concision is partly achieved by omitting needed detail.

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

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

For a destructive mutation tool with 0% parameter coverage and no output schema, the description is too thin. It omits lease-lifecycle semantics, error/idempotency behavior, and the meaning of the device parameters that an agent needs 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 0% across 3 parameters. The description sheds no light on leaseId (the sole required param), or on what deviceId/deviceName are used for, so it fails to compensate for a schema that documents none of its parameters beyond types.

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

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

States a specific verb ('Release') and resource ('the active foreground-control lease') plus the concrete side effect of dismissing the Windows overlay. It clearly reads as the inverse of foreground_control_acquire, but it never names that sibling or the pause/heartbeat alternatives, so differentiation is inferred rather than explicit.

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

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

No when-to-use context is given. It does not tell the agent that this must pair with a prior foreground_control_acquire, nor whether to use it versus foreground_control_pause, heartbeat, or status. The agent must infer the lifecycle position 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 establish the safe read-only, non-destructive, closed-world profile, so the burden is lighter. The description adds the payload contents (owner, task, pause state, heartbeat expiry), which is useful behavioral context, but says nothing about staleness, expiry semantics, or what happens when no owner 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 front-loaded sentence that enumerates the returned fields with zero filler. Nothing is repeated or 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?

There is no output schema, so the enumeration of returned fields is genuinely valuable, but the description does not compensate for the total absence of parameter documentation or the device-targeting behavior. Adequate but with clear gaps for a status tool whose main question is which device to query.

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?

Two parameters with 0% schema description coverage, and the description adds no meaning for deviceId or deviceName — not even whether they are optional or mutually exclusive. With no params the baseline would be 4; here the description leaves the selection of device 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 ('Return') plus resource ('foreground-control owner, task, pause state and heartbeat expiry'), so an agent knows exactly what is being read. It does not explicitly distinguish itself from the sibling family (foreground_control_acquire/heartbeat/pause/release), though the name and phrasing make it obviously the read-only counterpart.

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 foreground_control_acquire, foreground_control_pause, or foreground_control_release, and no stated prerequisites or exclusions. The sibling names hint at a state-machine workflow, but the description never tells the agent where this read fits in 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 destructive=true and readOnly=false, so the safety profile is covered. The description adds genuinely new behavior: replacements are validated and a file is not written if any of its replacements fail, which tells the agent about the per-file atomicity granularity. It says nothing about dryRun, concurrency, or cross-file atomicity.

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, front-loaded sentences with zero filler. The primary action comes first, the sibling constraint second, and the atomicity guarantee last.

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

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

It covers the core semantic and the per-file failure rule, but for a destructive 5-parameter mutation tool with no output schema and no parameter descriptions, it omits dryRun behavior, concurrency implications, device targeting, and any error/return expectations. Adequate minimum, clear gaps.

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

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

Schema description coverage is 0% across 5 parameters, so the description must carry the load and largely does not. It never mentions dryRun, concurrency, deviceId/deviceName, or the oldText/newText/replaceAll structure of a replacement.

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 (apply exact-text replacements) plus scope (many files, one call), which cleanly distinguishes it from fs_write_many and edit_block. It does not explicitly name those siblings, but the 'exact-text replacement' framing is precise enough for selection.

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

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

Gives a concrete when-not rule: main.cs requires fs_transaction with compile validation instead. That is a real routing condition, though it covers only one special case and says nothing about when to prefer this over fs_write_many or edit_block.

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

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

Annotations already declare this as a safe, non-destructive, closed-world read. The description goes beyond them by disclosing the path-resolution model: absolute paths are only allowed when RACCOON_FILESYSTEM_UNRESTRICTED=1, and relative paths anchor at RACCOON_ROOT. That environmental constraint is genuinely useful and not derivable from the structured fields.

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

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

Two tight sentences with the core action front-loaded and the path-resolution caveat immediately after. No filler or redundancy.

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

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

Annotations cover the safety profile and there is no output schema, lowering the burden, but the description still omits how `limit` behaves, what `deviceId`/`deviceName` do, and whether results are paginated. For a tool with four undocumented parameters this is only minimally 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?

Schema description coverage is 0% across four parameters, so the description must compensate, and it only partially covers `dir` (absolute vs relative resolution). It says nothing about `limit` (1–1,000,000), `deviceId`, or `deviceName`, leaving half the surface undocumented.

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

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

The description gives a specific verb and resource ("List one directory"), which is more precise than the bare title. However, it does not distinguish itself from the near-identical sibling `list_directory`, so an agent cannot tell the two apart from the text alone.

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

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

There is no guidance on when to use this tool versus `list_directory`, `fs_read_many`, or `get_file_info`. It states the path-resolution rule but never explains the selection context, leaving the agent to guess between competing filesystem tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context about memory behavior and repeat-call chunking, though it omits bounds semantics and any concurrency/rate notes.

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

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

Two tight sentences, front-loaded with the core capability and followed by the use case rationale. No filler or redundancy.

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

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

For a read-only tool whose annotations cover safety, the description is serviceable but thin against a 6-parameter schema at 0% coverage. The device-selection parameters and encoding semantics remain unexplained, so an agent could call it ambiguously for cross-device 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 description coverage is 0%, so the description must compensate for all six parameters. It loosely implies offset/maxBytes ('byte range') and encoding ('text or binary'), but says nothing about deviceId, deviceName, the utf8/base64 enum meanings, or the unusual negative offset bounds - leaving half the parameters undocumented.

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

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

The description states a specific verb and resource ('Read an arbitrary byte range from a text or binary file'), which clearly frames this as a partial/chunked read rather than a whole-file read. It implicitly distinguishes itself from full-read siblings like read_file, though it never names them explicitly.

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

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

Usage is only implied: 'Repeated calls can read files of any size without loading the whole file into memory' hints this is for large files, but it never states when to prefer this over read_file or fs_read_many, nor any exclusions.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the important behavioral idea that truncation is governed by byte budgets rather than lines, but omits what happens when the budget is exceeded, whether per-file failures abort the batch, and in what order results are returned.

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 well-formed sentence with the verb and the differentiating mechanism front-loaded. Nothing is padded or repeated.

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 six-parameter batch tool with zero schema descriptions and no output schema, the description is far too thin: it says nothing about device targeting, concurrency, truncation signals, or partial failure semantics. An agent could call it, but could not predict its results.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only gestures at paths and the byte-budget parameters. concurrency, deviceId and deviceName — three of six parameters — have no meaning explained anywhere, and even the budget parameters get no guidance on defaults or interaction between maxTotalBytes and maxBytesPerFile.

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 multiple UTF-8 files') plus the key scoping trait 'in one call', which separates it from single-file reads. It does not name a sibling (e.g. fs_read_chunk or read_multiple_files) explicitly, so differentiation is inferential rather than stated.

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

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

'Using byte budgets instead of line limits' implicitly contrasts this with line-based read tools and hints that it should be chosen for batch reads, but it never names an alternative or states when not to use it. Usage must be inferred from a single clause.

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

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

Annotations declare destructiveHint=true, and the description delivers real added value beyond that: strict UTF-8 input, persistent byte backup, forced BOM, atomic replacement, read-back verification, and — critically — that a compile failure restores exact original bytes. That rollback guarantee is exactly the behavioral detail an agent needs before invoking 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?

One dense semicolon-chained sentence front-loads the core concept, but the fragment 'main.cs requires validate.command to compile its project' reads like extracted example text and muddies rather than clarifies. Tight, but not cleanly 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 destructive multi-file mutation with nested objects and no output schema, the description richly covers behavioral traits but omits several parameters and never says what the 'integrity statistics' or read-back results look like. Enough to understand intent, insufficient to configure the call.

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

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

Schema coverage is 0% across five parameters including nested replacement and validate objects, so the description carries the full burden and mostly fails. It references validate.command and files implicitly, but says nothing about dryRun, deviceId, deviceName, replaceAll, or oldText/newText semantics, leaving them 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?

Opening phrase 'Transactional source edits' names a specific verb and resource, and the description adds the atomic-replacement/rollback characteristic that separates it from plain writers like fs_write_many or fs_apply_patch_many. It stops short of naming any sibling explicitly, so an agent must infer the boundary itself.

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 'use this when / use X instead' guidance anywhere. The only usage-flavored statement, 'Other files support optional validation,' describes behavior rather than a selection condition across the many file-editing siblings (edit_block, fs_apply_patch_many, fs_write_many).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the encoding options and the chunking/size claim, but does not state key behavioral details such as whether 'rewrite' truncates existing content, whether 'at' requires a valid offset, or whether a missing file is created.

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 dense sentences with no filler, and the write modes are front-loaded. It is appropriately sized, though slightly terse given the number of parameters it could have clarified.

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

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

For a 7-parameter mutation tool with 0% schema coverage and no output schema, the description covers the core write concept and the chunking rationale but omits device targeting, the offset requirement for 'at' mode, and truncation behavior on rewrite. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the semantics behind the 'mode' enum (rewrite/append/at byte offset) and the 'encoding' enum (UTF-8 vs base64), but leaves file, content, offset constraints, deviceId, and deviceName undocumented, covering only part of the 7 parameters.

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

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

The description states a specific verb (Write) and resource (file chunk) and enumerates the three write modes (rewrite, append, absolute byte offset), so an agent knows what the tool does. It does not, however, differentiate from close siblings like fs_write_text, fs_write_many, or edit_block.

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: 'Chunked calls remove any practical whole-file size limit' hints that this tool is for large writes that need chunking, but it never names fs_write_text or fs_write_many as alternatives nor states when a single whole-file write is preferable. No explicit 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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered structurally. The description adds useful behavioral context: create-or-replace semantics, UTF-8 text handling, concurrent execution, and per-file locking. It does not cover partial-failure behavior or rollback, but that is beyond what annotations 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?

A single front-loaded sentence with no redundant or filler text. It efficiently states the action, scope, and key behavioral traits.

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 nested file objects and no output schema, the description is too thin. It omits parameter semantics for deviceId, deviceName, and concurrency, and says nothing about failure handling across multiple files.

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 only alludes to 'many UTF-8 text files' and 'concurrently,' leaving files' nested structure, deviceId, deviceName, and concurrency 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?

The description names a specific verb and resource: 'Create or replace many UTF-8 text files.' It also adds distinguishing scope ('many') relative to single-file siblings like fs_write_text, and notes concurrency and per-file locking.

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

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

It implies use for batch file writing but never states when to prefer this over fs_write_text, fs_write_chunk, fs_apply_patch_many, or write_file. No exclusions or alternative-selection guidance is provided.

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 disclose readOnlyHint=false and destructiveHint=true, and 'Create or replace' is consistent with that overwrite semantics. The description adds value beyond the annotations by explaining path resolution (absolute paths gated behind RACCOON_FILESYSTEM_UNRESTRICTED=1, relative paths rooted at RACCOON_ROOT) and the validation requirement for main.cs. It does not describe encoding edge cases or atomicity, so it stops short of a 5.

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

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

Three compact sentences with the core action front-loaded, and each sentence adds distinct information (action, validation constraint, path rules). The middle main.cs sentence is tersely phrased but not wasteful.

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

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

For a destructive write tool with no output schema and 0% parameter coverage, the description covers path resolution and one special-case constraint, which is helpful. It still omits any explanation of the device parameters and content handling, so gaps remain for an agent calling 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 0%, so the description must carry parameter meaning, and it only partially covers the `file` parameter via the absolute/relative path rules. The `content`, `deviceId`, and `deviceName` parameters are left entirely undocumented in both schema and description, leaving most of the surface 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?

The opening sentence gives a specific verb+resource: 'Create or replace a UTF-8 text file,' which is clear and scoped. However, it does not differentiate itself from near-identical siblings such as write_file, fs_write_chunk, or fs_write_many, so an agent still needs schema inspection to pick correctly.

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 routes one specific case away from this tool: editing main.cs should go through fs_transaction with a compile validation command. That is a genuine when-not-use/alternative signal, but it covers only a single file and offers no general guidance on when to prefer this over the other write tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds the useful detail that four configuration domains are returned, but says nothing about scoping, freshness, or whether secrets are redacted — relevant since a secret_list sibling 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 front-loaded sentence with no padding. It is efficient, though slightly terse given the undocumented parameters.

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 is the only hint about the return shape, and it only names the domains without indicating structure or nesting. Combined with zero parameter documentation, an agent can call this safely (read-only, zero required params) but cannot predict what it will get back or what the device parameters do.

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

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

Schema description coverage is 0% for two parameters (deviceId, deviceName), and the description never mentions them. The agent cannot tell whether these select which device's config to fetch or are filters on the response, which is a material ambiguity for a config-reading tool.

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

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

Specific verb (Get) plus resource (configuration), and it enumerates the domains covered: runtime, host, workspace, compatibility. That is clearer than a bare name restatement, but it never distinguishes itself from the write-side sibling set_config_value, so an agent must infer that this is the read counterpart.

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 versus set_config_value, nor any prerequisite or context. Nothing tells the agent whether this reads global config or per-device config, which matters given the optional deviceId/deviceName parameters.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the return-content categories, but it says nothing about the deviceId/deviceName parameters implying access to files on a remote/connected device — a notable behavior left undisclosed.

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