Robot Actions — Remote Device Control

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

Adds substantial context beyond the annotations: a 10240-byte total cap, a 413 error on over-cap appends, and the lifecycle detail that saved notes surface at the start of each NEW chat rather than mid-conversation. These are behaviors an agent cannot infer from the readOnly/destructive hints.

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

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

Front-loads purpose in the first sentence, then usage triggers, then behavioral constraints and cap. Dense but every sentence carries operational weight; no filler.

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

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

With no output schema, the description still covers return semantics ('unless this tool returned success') and failure signaling (413 on over-cap). Combined with the lifecycle explanation, an agent has everything needed to call and report on this tool correctly.

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

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

The single 'block' parameter is fully documented in the schema (100% coverage), setting the baseline at 3. The description adds content-style guidance ('Markdown is encouraged; keep entries terse and factual (preferences, project context, references)'), which meaningfully shapes what to put in the block.

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: 'Append a block to the calling user's persistent agent memory.' The additive semantics clearly set it apart from agent_memory_replace by nature, but the description never names or routes against that sibling, so it stops short of full differentiation.

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

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

Gives explicit when-to-use triggers ('remember X', 'save this', 'note for next time'), a when-not clause ('Do not auto-update on ordinary messages'), and a mandatory same-turn ordering rule. This is exactly the routing guidance an agent needs.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new context beyond the annotations: a concrete 10240-byte cap and the resulting 413 error, plus the fact that the whole file is overwritten. It stops short of describing recovery or whether overwrites are reversible.

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

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

Three tight sentences, front-loaded with the core action, followed by the usage warning and the hard limit. No sentence is wasted and the most important constraint (use sparingly) is prominent.

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

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

For a single-parameter destructive tool with annotations covering the safety profile and a fully documented schema, nothing essential is missing. The cap and error behavior close the remaining operational gap.

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

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

Schema coverage is 100% and the schema already documents the single 'content' parameter, including the empty-string-to-clear behavior. The description adds no per-parameter syntax beyond the cap constraint, so the baseline 3 applies.

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

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

States a specific verb (replace) and resource (the entire memory file for the calling user), and explicitly contrasts with the sibling agent_memory_append. An agent can distinguish this from the append tool without opening either schema.

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

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

Explicitly says 'USE SPARINGLY — append is the safer primary' and names the three conditions that justify replace (drifted memory, stale entries, user-requested clean rewrite). This is textbook when-to-use vs. alternative 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 give readOnlyHint/idempotentHint/destructiveHint, but the description adds context they cannot: scroll:true 'CHANGES THE SCREEN: it scrolls the app and does not scroll back' and triggers lazy loading. It also discloses the important non-obvious limits (tap-target screening is a signal not a verdict, only on-screen drawn elements examined, ancestor-driven tappability invisible, contrast/text-size NOT checked).

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

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

Dense but front-loaded: purpose first, then fold/scroll guidance, then finding types, then limits. Every sentence carries information (finding semantics, rect-as-tap-point, caveats), though the block is long enough that an agent may need to scan rather than read once.

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

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

No output schema exists, yet the description covers the return shape (each finding carries label, class and pixel rect; rect centre is tappable via device_tap) and the aggregate caveat about summary.actionableNodes. Combined with the disclosed limits, an agent has everything needed to call and interpret 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 coverage is 100%, so baseline is 3; the description still adds real value, explaining why localeIsEnglish exists (English word matching for the redundant-description check), what maxScrollSteps bounds, and the side effects of scroll:true. It goes beyond restating the schema, though per-parameter coverage is already strong.

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

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

States a specific verb and resource with scope: 'Run an accessibility audit on the CURRENT screen of an Android device'. It also positions itself against the iOS sibling implicitly via platform and explains the rule basis (Google Accessibility Scanner). An agent can distinguish this from ios_accessibility_audit and device_page_source without opening a schema.

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

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

Explicit sequencing: 'navigate to the screen you care about FIRST (device_tap_by_text / device_launch_app), then call this', plus a named alternative behavior for scroll:true and a when-not-to condition ('Leave it off when the app must not be disturbed'). Nothing is left to inference.

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

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

Annotations already disclose the safety profile (readOnly=false, idempotent=false, destructive=false). The description adds useful behavioral context: cold launches are used, the command is named, and multiple runs are averaged. It does not detail side effects like force-stopping the app, but the annotations lower the 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?

Two tightly written sentences front-load the metric and mechanism with no wasted words. Each phrase adds technical specificity.

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

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

The description covers the purpose, method, and averaging behavior, and the schema fully documents serial and runs. It does not explain failure modes or device prerequisites, but for a simple measurement tool with no output schema, it is nearly complete.

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

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

Schema coverage is 100%, but the description adds meaning beyond it by explaining that the package input is resolved to a launcher activity and that results are averaged over N runs. This clarifies how pkg and runs are used behaviorally.

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 precise metric ('Cold app-launch time (ms)'), the underlying mechanism ('am start -W -S'), and the averaging behavior. This clearly distinguishes it from siblings like android_fps and android_performance_snapshot.

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

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

The description implies the tool is for measuring cold launch time, but it does not state when to use it over alternatives such as android_fps or android_performance_record_start. No exclusions or explicit context are 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine behavioral value by disclosing the output shape — including that `groups` are deduped by signature, sorted by count descending, and carry exampleIds — which no annotation or output schema provides.

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: the first front-loads the data categories, the second handles disambiguation. Every clause carries information an agent needs.

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

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

With no output schema, the description compensates by describing the return structure in detail, and annotations cover the safety/idempotency profile. Nothing material for correct invocation is missing.

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

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

Only one parameter (serial) and the schema documents it at 100% coverage including its origin (`device_list`). The description adds nothing about the parameter, so the baseline 3 is appropriate.

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

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

States a specific resource (crash/ANR/native-crash analytics) and enumerates exactly what it returns (totals, per-process, per-type, per-day timeline, deduped groups). It also explicitly contrasts itself with android_crash_detail, so an agent can pick between them without opening either schema.

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

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

Explicitly routes single-entry lookups to android_crash_detail, which is the main alternative an agent would confuse this with. It does not state prerequisites (e.g. that serial comes from device_list or whether the app must have run), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world behavior, so safety is covered. The description adds that the return is the full raw content (as opposed to a summary), which is useful context, but says nothing about size, pagination, or what 'raw' includes.

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 return nature and the id source 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 two-parameter read-only tool with full annotation coverage and 100% schema coverage, the description covers what is returned and where the id comes from. It could say more about the raw payload format, but nothing essential to calling it is missing.

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

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

Schema description coverage is 100%, so both parameters (id and serial) are already documented, and the schema itself states the id comes from android_crash_analytics. The description reinforces but does not extend the schema's parameter meaning.

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

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

The description names the specific resource (one crash/ANR/tombstone entry) and its scope (full raw content), which clearly distinguishes it from the analytics/list sibling. The retrieval verb is implicit rather than stated, but an agent can tell exactly what it returns.

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 points the agent to android_crash_analytics as the source of the id, implying the fetch-after-list workflow. It does not state when to prefer this over the analytics sibling or any prerequisites/exclusions, so usage is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the live-window attach semantics, that throttle/blockUrls/extraHeaders are cleared in a finally block and scoped to the capture window only, per-body (10 000) and total (200 000) body caps with bodiesOmitted/bodyTruncated/bodyError signals, and the default/max window bounds.

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

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

Front-loaded with purpose and the critical live-window caveat, then return shape, then options. It is dense and long, but justified by 13 parameters and no output schema; a few clauses (e.g. re-listing throttle profiles already in the schema) are redundant.

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

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

With no output schema, the description fully documents the return contract: the { records, bodiesOmitted? } summary shape, the HAR 1.2 alternative, every record field, and the throttle/total/returned extras. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter interaction context not present in the schema — how limit interacts with urlSubstring/onlyErrors and the token budget, that total/returned appear only when records were dropped, and that a top-level throttle field surfaces when throttling was active.

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 network requests made by a page running on the device ... via CDP') plus the mechanism (CDP Network domain, event set), so it is clearly distinct from native-traffic tools like android_traffic_* and from sibling DevTools tools. It never explicitly names an alternative or says when-not to use it, so it falls short of full sibling differentiation.

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

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

Explicit when/when-not guidance: pass triggerJs rather than triggering navigation from a separate tool call because the latter 'races the attach and returns 0 records'; use urlSubstring/onlyErrors to keep heavy pages within the token budget; omit pageId to auto-select the visible page; set includeBodies/throttle/blockUrls/extraHeaders only when needed for the window.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description adds value on top by disclosing the return shape ({ closed, pageId }) and the no-op outcome (closed:false if no such page). It doesn't mention auth or socket behavior, but the annotations already do the heavy lifting.

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

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

Three tight sentences: action first, then purpose/routing, then return contract. No filler, nothing repeated from the schema.

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

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

With no output schema, the description supplies the return contract itself, plus the pageId prerequisite and cleanup rationale. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents udid, pageId (including its origin in android_devtools_list_pages), and socket. The description reinforces the pageId source but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Close a debuggable tab/page on the device by pageId') plus the underlying mechanism (CDP /json/close). It is clearly distinguishable from android_devtools_list_pages and the other android_devtools_* siblings.

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

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

Explicitly says when to use it ('clean up stale tabs that accumulate across sessions and clutter android_devtools_list_pages') and where to get the required pageId. It does not name a when-not condition or an alternative close path, but none is needed here.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses that it enables Runtime and Log domains, subscribes to specific events, returns a normalized entry array, and — critically — that it only captures events fired AFTER attach. That live-window caveat is essential behavioral context an agent cannot infer.

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

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

Front-loads purpose, then mechanism, then return shape, then the crucial race caveat and defaults. Sentences are dense but each one carries non-redundant information (event names, latency window, defaults, auto-select).

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 compensates by specifying the exact return shape ({ level, text, url?, lineNumber? }). Combined with the attach-window semantics and parameter defaults, an agent has everything needed 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 coverage is 100%, and the schema already documents the default (3000ms), max (15000ms), triggerJs race-free rationale, and pageId auto-pick. The description largely restates this, so the baseline of 3 applies; it adds no syntax or format detail absent from the schema.

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

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

States a specific verb and resource ('Collect console logs, exceptions, and log entries from a page running on the device') and scopes it to a time window. It is clearly distinguishable from siblings like android_devtools_capture_network and web_console_messages, and even lists the exact CDP events it listens to.

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 strong conditional guidance: it warns that triggering logging from a separate tool call races the ~1-3s attach latency and is silently missed, and directs the agent to use triggerJs instead. It does not name an alternative sibling tool for the non-live case, so it falls short of a full 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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds valuable context beyond that: the CDP fallback to document.cookie (which limits results to non-httpOnly cookies) and the specific cookie attributes 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?

Two compact sentences with no wasted words. The purpose is front-loaded, followed by fallback behavior and parameter hint, all of which earn 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 read-only tool with full schema coverage, safety annotations, and no output schema, the description provides sufficient context: what it returns (cookie fields), how it retrieves them, fallback behavior, and parameter defaulting. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds a useful clarification that omitting pageId auto-selects the visible/active page, which is more specific than the schema's 'auto-picked 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 'Get' and resource 'cookies' with scope 'for a page on the device via CDP', and names the exact CDP method. It is clearly distinguishable from sibling devtools tools like android_devtools_capture_network or android_devtools_console_logs.

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?

Provides a use case ('useful for debugging auth/session state') but does not name alternatives or conditions when this tool should not be used. The parameter hint about pageId omission is more about parameter semantics than usage guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior: the exact return shape, that suggested locators are verified unique before being offered, the null-suggested edge case, and that css is an nth-of-type chain over layout classes not fit for page objects. This is context well beyond structured fields.

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

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

Front-loaded with purpose and return shape, and every sentence carries weight (fallback warnings, null handling, style flag, page auto-select). Some sentences are dense multi-clause runs, but there is little pure filler.

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

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

With no output schema, the description carries the full burden and does so: it enumerates returned fields (tag, text, attributes, classes, bbox, visibility), the suggested/playwright/css/xpath structures, and the null case. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: selector scopes extraction to matching elements vs the interactive/meaningful default, includeStyles returns a curated computed-style set, and omitting pageId auto-selects the visible/active page. That is genuine semantic enrichment over the schema strings.

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 (extract) and resource (locator-friendly element data from a device page), plus the downstream purpose (building Playwright/Selenium locators). An agent can distinguish this from android_devtools_get_dom, device_find_element and device_locators_for without opening any schema.

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

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

Strong prescriptive guidance: 'USE suggested', css/xpath are diagnostic fallbacks not recommendations, when suggested is null act via ref, set includeStyles for computed styles, omit pageId to auto-select. It lacks an explicit contrast with sibling tools like android_devtools_get_dom, but the in-tool usage rules are clear and actionable.

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, which the description does not contradict. The description adds valuable behavioral context about what is returned (result value, exception details, pageId/pageUrl) and the pageId auto-selection semantics. It doesn't explain why destruction is possible, but the return-value and tab-targeting details are non-obvious and genuinely useful.

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

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

Two tightly packed sentences with no filler. The CDP-mechanics detail is front-loaded, followed by return-value and pageId guidance. Slightly dense but 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 CDP evaluate tool with rich annotations and a full schema but no output schema, the description covers the operation, the return shape (result, exceptions, pageId/pageUrl), and the page-targeting rule. Minor gap: it doesn't warn about the destructiveHint or when evaluation could mutate page state, but otherwise complete.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds a nuance about omitting pageId (auto-select active tab, post-navigate binding) that enriches semantics beyond the schema's terse note, keeping it above baseline.

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

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

States a specific verb (evaluate) and resource (JavaScript expression in a device page via CDP) and names the underlying CDP method call (Runtime.evaluate). Distinct enough from siblings like ios_safari_evaluate and webpage_cdp_command that an agent can select it 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?

Provides implicit guidance for pageId selection ('omit pageId to auto-select the active tab; after a navigate, that is the tab the navigate landed on'), but does not explicitly contrast with alternatives that could also evaluate JS (webpage_cdp_command, session_execute) or specify when to prefer this 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context the annotations don't carry: the 100,000-character output cap and the appended truncation notice, which directly affects how an agent should handle the result.

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

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

Three short sentences, front-loaded with the core action, then the output-size constraint, then the parameter default. No filler or restatement of the title.

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

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

No output schema exists, so the description must carry the return contract, and it does: outerHTML of the page or matched element, with the size cap and truncation behavior disclosed. Annotations cover safety. The only gap is the lack of routing guidance against sibling DOM/page-source tools.

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

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

Schema coverage is 100%, so baseline is 3. The description goes slightly beyond the schema by spelling out what 'auto-picked' means for pageId — the visible/active page — which the schema only labels 'auto-picked when omitted.' Selector semantics are already in the schema, so the added value is modest.

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: 'Get the outer HTML of the page (or a CSS-selector-matched element) running on the device via CDP.' An agent knows exactly what it returns, but the description never distinguishes it from close siblings like android_devtools_elements or device_page_source, which also expose page structure.

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 only guidance is 'Omit pageId to auto-select the visible/active page,' which explains a parameter default rather than when to pick this tool over android_devtools_elements or device_page_source. Usage context is implied by the CDP/outerHTML framing but no alternatives or exclusions are named.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial extra behavior: result ordering (newest-active first), the meaning of `active: true` as the default resolution target for other tools, the WebView-only nature of `visible` (null on ordinary browser tabs), and the caveat that stale tabs accumulate across sessions.

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

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

Front-loaded with purpose and return shape, then dense, non-redundant guidance about active vs visible and the close_page follow-up. Every sentence carries unique, actionable information; nothing is padding.

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

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

There is no output schema, so the description must describe returns — and it does (id, type, title, url, active, visible, ordering). Combined with the active/visible semantics and stale-tab caveat, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% for both parameters (udid, socket) with their own descriptions, so the schema already carries the parameter burden. The description adds nothing about the parameters themselves (pageId is referenced only as a parameter of other tools), so the baseline 3 applies.

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

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

States a specific verb (list) and resource (debuggable pages/targets on the device) and immediately enumerates the returned fields, so an agent knows exactly what it gets. It is clearly separable from android_devtools_close_page and the many android_devtools_* action 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?

Explicitly tells the agent when NOT to call it for a lookup purpose: 'you do NOT need to list tabs and pass an id just to act on the current tab, only to act on a DIFFERENT one.' It also names the follow-up tool (android_devtools_close_page) for cleaning up stale tabs, giving both context and an alternative.

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

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

Goes well beyond the annotations: routes apply immediately, survive navigation, nothing is changed device-wide, no certificate is installed, and the effect is scoped to the page. It also clarifies the update-in-place semantics when an id matches. This is exactly the kind of side-effect and scope disclosure a mutation tool 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?

Front-loads the core action and then layers the constraints in ordered sentences with a clear WEB CONTENT ONLY callout. It is dense but every sentence carries information; slightly long, but appropriately so for a 14-parameter tool.

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

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

Given 14 parameters, rich annotations, and no output schema, the description covers scope, effect lifetime, mode semantics, and the sibling alternative. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters with enums and defaults. The description reinforces the meaning of mode and id but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (add/update-in-place) and resource (a mock/abort routing rule) and immediately names the scope (Chrome/WebView requests on this device). It also explicitly distinguishes itself from the sibling android_traffic_mock_add, so an agent can tell the two apart without opening either schema.

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

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

Explicitly says when to use each mode (mock serves a canned response, abort fails the request) and when NOT to use this tool, routing the agent to android_traffic_mock_add for native app code. The alternative and its selecting condition are named outright.

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, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: it deletes ALL routes (not one), disables interception, and restores normal networking for the device's browser.

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 zero waste: scope/effect first, then the usage trigger. Nothing redundant 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?

For a destructive teardown tool, annotations cover reversibility/idempotency and the description covers scope, effect, and timing, and no output schema is expected to be explained. Only minor detail missing (e.g. behavior when no routes are armed) keeps it from a 5.

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?

Single udid parameter with 100% schema description coverage, so the schema carries the meaning; "this device" only loosely ties the action to the parameter. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (remove ALL Chrome/WebView routes for this device) plus the secondary effect of un-arming interception, which separates it from mock_add. It does not explicitly name mock_remove/mock_list, so the contrast with the per-route removal sibling is left implicit.

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

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

"Call this when finished" gives a clear trigger condition for teardown, which is exactly the lifecycle guidance an agent needs. It stops short of naming the alternative (mock_remove) for removing a single route, so no explicit when-not is 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 cover readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is handled. The description adds genuinely non-redundant behavior: matching is first-match-wins, the effect is scoped to the page, no certificate is installed, and nothing is changed device-wide. It stops short of describing the returned entry structure.

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

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

Three compact sentences, front-loaded with what is listed and in what order. The two follow-up sentences are scope/reassurance rather than filler, though the 'never will be by this tool' clause is slightly emphatic for the space it occupies.

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

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

For a single-parameter read-only list with full schema coverage and annotations, the description supplies the missing behavioral context (ordering, scope limits). Since there is no output schema, it would be marginally better if it hinted at the fields of a returned route, but nothing critical to invoking it correctly is absent.

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

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

There is only one parameter (udid) and schema description coverage is 100%, so the schema already documents it fully. The description contributes no additional meaning about the udid argument, which is the baseline-3 case for a fully covered single 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 (List) and resource (Chrome/WebView mock/abort routes registered for this device), plus the ordering semantics (match order, first match wins). That is enough to distinguish it from mock_add/mock_remove/mock_clear, but it does not explicitly contrast itself with the close sibling mock_status, which is the one an agent could plausibly confuse it with.

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

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

The description clarifies scope (web content only, native app requests not intercepted) which implicitly tells the agent when this tool is relevant, but it never names an alternative tool or states a when-to-use condition versus mock_status or the traffic-mock equivalents. Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real behavioral context beyond them: removing the last route automatically un-arms the device so traffic is not paused needlessly — a non-obvious side effect an agent could not get from 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 resource, with the second sentence dedicated to the side effect. No filler and nothing redundant with structured fields.

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

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

For a two-parameter mutation with annotations covering destructiveness and idempotency, the description is nearly complete; the auto-un-arm behavior is the key extra. It omits what happens when the id is unknown or the device is not armed, which is a minor gap.

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

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

Schema description coverage is 100% with only two simple parameters (id, udid), so the schema already carries the meaning. The description adds nothing about parameter format or the id's provenance beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific verb (remove), resource (one Chrome/WebView route) and lookup key (by id), which distinguishes it from bulk siblings like android_devtools_mock_clear. It does not, however, explicitly contrast itself with android_traffic_mock_remove or ios_safari_mock_remove, so an agent must infer the platform boundary.

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: remove a previously added mock route. No when-to-use/when-not guidance, no named alternative (mock_clear would be the obvious one), and no prerequisites such as needing an active DevTools page. The id source is mentioned in the schema, not here.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuine context beyond that: the meaning of each counter category and the diagnostic insight that a non-matching route reports mocked: 0. It does not discuss error states of the status call itself, keeping it at a 4.

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

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

Two sentences, zero filler, and the enumeration of reported fields is front-loaded ahead of the diagnostic tip. Every clause carries information.

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

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

With no output schema, the description must convey what comes back, and it does: the armed flag, target, routes, and named counter values. Combined with annotations covering the safety profile and 100% param coverage, an agent has everything needed to call and interpret it.

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

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

There is a single parameter (udid) with 100% schema description coverage, so the schema already documents it fully. The description adds no format or constraint detail about the device id. Baseline 3 is appropriate when the schema does all the work.

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

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

The description uses a specific verb ('Report') and enumerates exactly what is reported: armed state, attached page target, active routes, and hit counters. This is far more informative than the name alone. It does not explicitly distinguish itself from nearby siblings such as android_devtools_mock_list, 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?

It gives a concrete diagnostic condition for using the tool: 'Check the counters to confirm a mock is actually firing — a route that never matches shows mocked: 0.' That is clear when-to-use guidance. It names no alternative or exclusion (e.g., vs. mock_list or mock_add), so it is not a full 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?

Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=true) by spelling out the waitMs gating rule, that waiting blocks on a Page.frameStoppedLoading event, that finalUrl is only populated when waitMs>0, and that success mutates device page state affecting later calls. Redirect visibility and the auto-select default are exactly the behavioral traits an agent needs.

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

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

Front-loaded with the action and mechanism, then behavior and return shape; every sentence carries information. It is dense with parentheticals and would read faster split into shorter lines, but there is no filler.

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

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

With no output schema, the description fully documents the return shape (url, finalUrl, loaderId, errorText, frameStoppedLoading) plus the conditional that governs finalUrl. Together with the 100%-covered input schema and annotations, an agent has everything needed to call it correctly and chain follow-up calls.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics on top: the waitMs>0 condition that makes finalUrl observable, the consequence of omitting pageId, and the fact that the selected page becomes current for later calls. Only 'socket' is left unelaborated beyond its schema default.

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 (navigate) and resource (a page running on the device) and pins the mechanism via CDP Page.navigate, which cleanly separates it from device_navigate_url, web_navigate and webpage_navigate. An agent can tell exactly what it does without opening the schema.

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

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

Gives clear usage context: omit pageId to auto-select the visible/active page, and after success the landed page becomes the device's current page so subsequent android_devtools_* calls need no pageId and no list_pages round trip. It does not explicitly contrast with the non-CDP navigation siblings (device_navigate_url, web_navigate), so the 'when not to use this' half is missing.

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, idempotentHint, and non-destructive, so the safety profile is covered. The description adds the non-mutating data source (dumpsys gfxinfo), but discloses no operational caveats such as whether the app must be running or that gfxinfo stats are cumulative since last reset.

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

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

A single front-loaded sentence with zero filler; the parenthetical metric list earns its place by telling the agent exactly what comes back. No redundant restatement of the title or schema.

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

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

With no output schema, the description usefully enumerates the returned metrics (jank %, percentiles, missed vsyncs). Combined with fully documented params and safety annotations, this is nearly complete, though it omits prerequisites for obtaining meaningful stats.

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

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

Schema description coverage is 100%, with both 'pkg' and 'serial' documented (including an example and a reference to device_list). The description adds no further parameter meaning, which is the correct baseline 3 when the schema does the heavy lifting.

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

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

The description states a specific resource and scope (FPS/jank stats for a package) and even names the underlying mechanism (dumpsys gfxinfo), so an agent can tell what it returns. It does not explicitly differentiate from potential siblings like android_performance_snapshot, 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?

Usage is implied by the metric provided (fetch FPS/jank for a package), but there is no explicit when-to-use, when-not-to-use, or named alternative such as android_performance_snapshot. This is the minimum-viable level of 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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds substantive traits: no new full-resolution grab is spawned, capture is at physical resolution with no downscaling, and no page-source is bundled. It omits the failure behavior when the shared stream is not already running, which is the one precondition it implies but never states.

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

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

Front-loaded with the PREFERRED/ALREADY-RUNNING qualifiers and the core tradeoff; each sentence carries information. Slightly repetitive in restating the resolution invariant that device_screenshot already promises, which 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 single-param, no-output-schema read tool, the description covers return format (single JPEG frame), the fast-path rationale, and the sibling tradeoff. The main gap is not stating what happens if the shared stream is not running, a precondition this tool depends on.

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

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

Only one parameter (udid) and schema description coverage is 100%, so the schema fully documents it. The description adds no format or sourcing detail for udid, so the baseline 3 applies.

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

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

States a specific verb+resource (screenshot of an Android device) and a distinguishing mechanism (single JPEG frame decoded from the already-running MJPEG stream, no fresh grab). It explicitly names and contrasts with the sibling device_screenshot, so an agent can separate the two without opening either schema.

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

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

Explicitly says when to use it ('routine per-action screen checks', 'make it your default for iterating on a flow') and when not ('reserve device_screenshot for when you need the bundled labeled-elements list or a full-fidelity image'). Alternatives and selection criteria are both given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so safety is covered. The description adds the session lifecycle fact that recording must be explicitly stopped, but says nothing about rate limits, what happens on a second start, or where metrics surface, so it only modestly extends 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, no waste, with the core action front-loaded and the stop counterpart as a closing pointer. Nothing redundant.

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

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

For a three-parameter start tool with no output schema and annotations covering the safety profile, the description is nearly sufficient. The one small gap is that it does not say where the recorded metrics are retrieved (stop return vs snapshot), which an agent must infer.

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

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

Schema description coverage is 100%, so all three parameters (serial, pkg, intervalMs) are already documented with defaults and bounds. The description adds no syntax or format detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb ('Start recording') plus the resource and scope ('per-process CPU/memory over time'), and explicitly names the paired sibling android_performance_record_stop, so an agent can place it against the stop/snapshot tools without opening a schema.

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

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

It gives clear context for use (continuous metrics capture) and routes the agent to android_performance_record_stop for termination, which is the essential workflow pairing. It does not, however, distinguish when to prefer this recording over android_performance_snapshot or android_fps.

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 generic safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds substantial behavioral context beyond that: the ~15 s sampling interval, the 'throttling = MODERATE or above' threshold, the 60 s minimum before a baseline block appears, frames only when a package is focused, and the explicit limitation that battery drain is not measured.

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

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

Front-loading is good ('Stop a performance recording and return...'), but the rest is a single dense wall of text mixing return-value fields, thresholds, and caveats with no hierarchy. Given there is no output schema the detail is warranted, but the packing hurts scannability.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so comprehensively for a complex tool (per-process metrics, derived facts, thermal, baseline, frames). It is only slightly incomplete in not clarifying whether the session is consumed/terminated by the stop.

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

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

Only one parameter (sessionId) and schema description coverage is 100%, so the schema already fully documents it. The description adds no format or provenance detail beyond what the schema's own 'Session id from android_performance_record_start' note provides, which is the expected baseline.

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

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

States a specific verb ('Stop') and resource ('a performance recording') and immediately enumerates what it returns (time-series, per-process summary, thermal/frames/baseline blocks). This clearly distinguishes it from the sibling android_performance_record_start and android_performance_snapshot without needing to name them.

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

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

Usage is only implied: the sessionId param note ties it to android_performance_record_start, so an agent can infer this is the closing call of a record session. There is no explicit when-to-use vs snapshot/start guidance, no statement of whether stop can be called twice, and no 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful context that the data comes from `top` and which metrics are captured, but says nothing about sampling cost, latency, or how the single snapshot relates to the record_start/record_stop flow.

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-loading what the tool returns before the parameter modes. No filler, though the escaped '%%' is a minor readability blemish.

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 snapshot tool with no output schema, the description adequately states the returned metrics (CPU %, memory MB) and the two scoping modes, and annotations cover safety. Missing only a note on return shape (e.g., listing format) to be fully self-sufficient.

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

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

Schema description coverage is 100%, so all three parameters are already documented; the baseline is 3. The description adds mild reinforcement by restating that topN ranks by CPU and pkg selects a single app, but no syntax, default, or edge-case detail beyond the schema.

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

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

The description names a specific verb ('Snapshot'), the exact resource measured (per-process CPU % and memory in MB), the platform (Android) and the mechanism (`top`). An agent can distinguish it from siblings like android_performance_record_start/stop or android_fps, though it never explicitly contrasts itself 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?

It clarifies the two operational modes ('Top-N by CPU, or one app via pkg'), which implies when to use each parameter, but gives no when-not-to-use guidance and does not point to alternative tools such as the recording start/stop pair for continuous profiling.

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?

Far exceeds the annotations (readOnlyHint false, destructiveHint false, idempotentHint false): discloses ~5 s enable/disable latency, ~3 s per action, the meaning of code values ('not_running', 'text_unavailable', 'not_installed'), the side effect that single taps only move focus while TalkBack is on, and the automatic silence/local-versus-remote audio behavior — none of which the annotations 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?

Front-loads purpose and the action catalog, then error codes and side effects; every sentence carries information. It is long and dense, but the length is justified by the multi-action surface and the important error/side-effect caveats.

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 fully documents the return fields (code, enabled, running, text, className, bounds) plus the caveat that 'text' is composed rather than verbatim spoken output. Nothing an agent needs to invoke or interpret the tool correctly is missing.

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

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

Schema coverage is 100% and the enum already lists the action values, so the baseline is 3; the description nonetheless adds real meaning by explaining what each action does (gesture semantics for next/previous, double-tap for activate) and clarifying 'status' is a no-op. It does not add format detail for udid beyond the schema, so it is not a full 5.

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

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

States a specific verb (Drive) and resource (Android's TalkBack screen reader) and enumerates every action with its meaning, so an agent can match intent without opening the schema. It is clearly distinguishable from siblings like android_accessibility_audit and pairs the alias 'start'/'stop' with ios_voiceover.

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

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

Gives clear operational conditions: enable TalkBack first when code is 'not_running', disable it when done because taps/swipes change behavior, and notes 'status' changes nothing. It does not explicitly contrast with alternative accessibility tools, so it stops short of naming when-not-to-use 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds meaningful behavioral context beyond them: traffic is DECRYPTED HTTPS, bodies are truncated when includeBodies is set, and only the most recent `limit` flows are returned. It omits whether capture must be active (fails silently vs errors) and any retention window.

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

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

Front-loaded with the core action and scope, then the returned fields, then the optional behaviors and filters. Four compact sentences with essentially no filler, though the field enumeration sits a bit dense.

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

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

No output schema exists, so the description usefully enumerates the return shape (method, url, host, status, contentType, sizes, durationMs) and the body-truncation behavior. Combined with the 100%-covered input schema, an agent has what it needs, though pagination/retention semantics are only partially addressed via `limit`.

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

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

Schema description coverage is 100%, so every parameter (limit, serial, onlyErrors, urlSubstring, includeBodies) is already documented in the schema. The description restates the includeBodies behavior and filters but adds little beyond what the schema provides, which is the expected baseline-3 case when the schema does the heavy lifting.

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

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

States a specific verb+resource (snapshot decrypted HTTPS flows) and lists the fields each flow contains, making the tool's output concrete. It ties itself to the capture lifecycle via 'since android_traffic_start', which implicitly separates it from android_traffic_status and android_traffic_stop, but it never names a sibling or explicitly distinguishes itself from the mock tools.

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

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

The phrase 'captured since android_traffic_start' implies the prerequisite that capture must be running, and the filter options hint at use cases (finding errors, matching URLs). However, there is no explicit when-to-use guidance, no statement of when to prefer android_traffic_status or the mock tools, and no mention of the iOS counterpart ios_traffic_flows.

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

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

With annotations only covering safety flags, the description carries real behavioral weight: per-device storage, live effect with no restart, mock-vs-abort outcome (canned response vs killed connection), and the certificate-pinning limitation. The 'update in place if id matches' semantics are consistent with idempotentHint=false.

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

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

Dense and front-loaded, leading with the verb and the update-in-place caveat. Every clause carries information (prerequisite, live effect, pinning limit), though the multi-clause sentence is heavy and could be split for readability.

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

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

For a 12-parameter mutation tool with no output schema, the description covers purpose, prerequisites, live behavior, and limitations well. The one gap is that it never says what is returned (e.g. the generated route id), which matters for follow-up calls to mock_list/mock_remove.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for key parameters: it explains mode 'mock' vs 'abort' behavior and the id-driven update-in-place path. Other params (headers, delayMs, matchType) are left to the schema.

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

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

States a specific verb+resource (add/update a mock or abort route) and precisely scopes it to the TLS-inspecting proxy on this device, distinguishing it from sibling tools like android_traffic_mock_list/remove and android_traffic_start. It even clarifies the update-in-place semantics when `id` matches.

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

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

Gives a clear precondition (TLS capture must already be running via android_traffic_start) and an explicit exclusion (certificate-pinned apps can never be intercepted, so such routes never match). It does not name sibling alternatives (e.g. android_devtools_mock_add, webpage_mock_add) for the non-Android case, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds only scoping ('for this device'); it says nothing about return format, ordering, or whether it includes abort routes separately.

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 no filler, front-loading the verb and resource before the cross-reference. 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 read-only list tool with no output schema and one fully documented parameter, the definition covers purpose and scope adequately. It could note what the listing returns, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100% and there is a single serial parameter fully documented in the schema, so the baseline is 3. 'For this device' loosely reinforces that serial targets a device but adds no format or syntax detail.

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 (mock/abort routes configured for this device), clearly distinct from mock_add and mock_remove siblings. It cross-references the companion add tool rather than naming what it is not, so sibling differentiation is partial.

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 'currently configured for this device' establishes the scenario for calling it, and the pointer to android_traffic_mock_add implies the setup relationship. No explicit when-not-to-use or alternative-tool routing is 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, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, so the bar is lower. The description adds return behavior ('Returns the resulting route list') and the `all`-vs-`id` scope distinction, which is useful context beyond the structured hints.

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?

Single front-loaded sentence with zero waste: it covers the two removal modes and the return value. 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?

Covers what the tool does, both removal modes, and the return value. With annotations carrying the destructive/idempotent profile and the schema documenting params, only the explicit when-to-use decision and any error/partial-failure behavior are missing.

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

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

Schema description coverage is 100%: both `id` and `all` are already fully documented in the schema, including that `id` comes from add/list. The description only restates the same semantics, adding no new syntax or edge-case meaning.

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

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

States a specific verb+resource: 'Remove one mock/abort route by `id`, or every route on this device when `all` is true.' Distinguishes from sibling android_traffic_mock_add/list by naming the operation and scope.

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 through the two mutually exclusive paths (single `id` vs `all`), but never explicitly says when to prefer `all` over `id` or when removal is necessary. The sibling add/list tools are referenced only in the schema, not the description.

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

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

The annotations declare this is a non-read-only, non-idempotent, non-destructive write, and the description adds substantial behavior beyond that: the two install modes (dpc vs manual), that the Device Owner path installs the proxy AND CA silently with zero on-device interaction, the fallback to an adb global proxy, and the cert-pinning limitation. This is unusually rich disclosure for a mutation tool.

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

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

The action is front-loaded in the first clause and every sentence carries information (mechanism, install modes, prerequisites, follow-up tool, limitation). It is dense and parenthesis-heavy with mode labels and path names, which is slightly taxing 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 one-parameter mutation tool with no output schema, the description covers mechanism, both execution paths, prerequisites, the natural next tool, and the failure mode (pinned apps). Nothing an agent needs to call it correctly is missing.

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

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

There is a single parameter (serial) with 100% schema description coverage, so the schema already documents it fully. The description frames the operation as per-device but adds no format or syntax detail for the serial beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (start TLS inspection) and resource (Android device traffic) and describes the concrete mechanism: bringing up a per-device TLS-inspecting proxy and pointing the device at it. It explicitly distinguishes itself from Chrome DevTools and names the companion read tool android_traffic_flows, so an agent can place it against siblings without opening a schema.

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

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

Gives clear when-to-use context (native app HTTPS capture, which DevTools cannot do), the prerequisite that the app must already trust user certificates, and the follow-up step (drive the app and read flows with android_traffic_flows). It also states the exclusion that certificate-pinned apps will not decrypt, which is exactly the kind of routing information an agent needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds what fields are reported but says nothing about auth requirements, whether a stopped capture returns an error or an 'inactive' status, or other behavioral edge cases.

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 reported fields are listed in priority order and every clause carries information.

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

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

With no output schema, the description usefully enumerates the return fields (TLS state, proxy mode, buffered flow count), which is the main thing an agent needs. Minor gap: it doesn't clarify what 'buffered' means or whether counts are cumulative, but for a simple status probe this is close to complete.

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

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

Only one parameter (serial) and schema description coverage is 100%, so the schema already documents it fully. The description adds no additional meaning about the serial argument, making the baseline 3 appropriate.

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

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

States a specific verb ('Report') and enumerates exactly what is returned: TLS inspection state, proxy mode (dpc/manual), and buffered flow count. This clearly separates it from android_traffic_flows (lists flows) and android_traffic_start/stop (mutate capture state).

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

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

Usage is implied (check traffic capture status for a device), but there is no explicit when-to-use or when-not-to-use guidance, and no routing to sibling tools like android_traffic_flows when the agent actually wants the buffered flow contents.

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

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

Goes well beyond the annotations, which only say readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description discloses consumer-scoped reference counting, the stillRunning: true response signal, and exactly what is destroyed when the last consumer stops (proxy killed, device proxy/CA cleared, buffered flows discarded).

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

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

Three sentences, front-loaded with the action and its scope, then the non-obvious conditional behavior. Dense but essentially waste-free; the final sentence is long yet each clause (killed proxy, cleared CA, discarded flows) carries distinct information.

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

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

No output schema exists, and the description pre-emptively covers the key return signal (stillRunning: true). Given a single fully-documented parameter and the teardown semantics explained, nothing needed to invoke or interpret this call is missing.

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

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

Schema coverage is 100% and the single 'serial' parameter is fully documented as the adb serial. The description adds no format detail or constraints beyond 'for an Android device', so the schema does the work — baseline 3 is correct for a fully-specified single 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 and resource ('Stop TLS inspection for an Android device') plus a precise scope qualifier ('from THIS (AI) consumer only'). An agent can distinguish it from android_traffic_start and ios_traffic_stop without opening any schema.

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

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

Explains the condition under which stopping actually tears down proxies ('Only when every consumer has stopped') versus when resources are left running for other consumers. It does not name the counterpart tool (android_traffic_start) or state prerequisites, so it stops short of explicit alternative routing.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, but give no sense of what actually happens. The description fills that gap: the URL is short-lived, single-device, browser-openable, and the server transcodes the live stream to MJPEG on the fly. It doesn't say whether repeated calls spawn multiple transcodes or how/whether a stream is stopped, which is the remaining unknown for a non-read-only 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?

Three tight sentences, front-loaded with the core capability, then the return-value shape, then the intended use. No filler or restatement of the title.

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

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

With no output schema, the description correctly explains the return value (a short-lived viewer URL) and the required follow-up action (open it directly in a browser). The only gaps are operational details an agent might want, such as URL lifetime and whether the stream needs to be torn down, which is a minor omission rather than a blocking one.

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

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

Only one parameter (udid) with 100% schema description coverage ('Device serial number (UDID)'), so the schema carries the meaning. The description adds only that the resulting URL is bound to a single device, not new syntax or format detail for udid. Baseline 3 is appropriate.

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

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

Specific verb (Get) plus resource (LIVE video-stream link) and scope (Android device, single-device, real-time). It explicitly contrasts with device_screenshot ('one frame'), so the agent can distinguish it from the nearest sibling without opening either schema.

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

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

Gives a clear use case ('Use this to let a person supervise what the agent is doing on the device') and distinguishes the live-stream case from the one-frame screenshot case. It stops short of stating when-not to use it (e.g. for automated analysis, use device_screenshot/MJPEG instead) or any device prerequisites.

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 description goes beyond the annotations by explaining WHY the idempotentHint/destructiveHint=false profile holds: Android live views own no state, the viewer's lifetime is tied to the device session and connection, so there is nothing to release. That is real behavioral context an agent cannot infer from readOnlyHint=false plus idempotentHint=true.

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

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

Three short sentences, front-loaded with the cross-platform rationale, followed by the reason no cleanup occurs and the safety note. Nothing is padded, though "accepted so one flow works on both platforms" arguably restates the first clause's 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 one-parameter, no-output-schema, no-op tool whose annotations already declare the safety profile, the description supplies everything needed: what it is, why it exists, that it holds no resources, and that it is always safe to 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?

There is a single parameter, udid, and schema description coverage is 100%, so the schema already carries the semantics. The description adds no meaning about udid or about what identifier form is acceptable, so the baseline 3 applies.

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

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

The description identifies this as the Android counterpart of ios_vnc_close_hid, a compatibility stub that closes an Android live view, which distinguishes it from every other android_* sibling. It is slightly indirect in that it explains the rationale (nothing to release) rather than stating the verb+resource in a leading clause, but the purpose 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?

"Safe to call at any time" gives explicit permission to invoke unconditionally, which is exactly the guidance needed for a no-op compatibility tool. It does not mention the natural pairing with android_vnc_open or state any when-not condition, but for a harmless stub there is little more to exclude.

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

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

With annotations only covering the safety profile (not read-only, not destructive, not idempotent), the description adds the operationally critical details: the page self-authenticates for ~5 minutes, keeps working for 30 minutes, reconnects after a drop, and is bound to 'the user currently holding this device -- share with care'. It also states the view's lifetime is the device session, which explains the non-idempotent/non-destructive hints.

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

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

Front-loaded with the purpose and the key delivery instruction, and nearly every clause carries real information. It is nevertheless dense for a one-parameter tool, with overlapping lifetime statements (5-minute auth, 30-minute page, session-length view) that could be tightened.

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

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

There is no output schema, but the description enumerates the returned JSON fields and explains what each is for (viewerUrl to hand to the user, websocketUrl as a raw RFB stream with subprotocol and no password, width/height as device pixels matching device_tap coordinates). Nothing an agent needs to call or interpret the result is missing.

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

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

Schema coverage is 100% for the single udid parameter, so the schema already carries its meaning. The description's coordinate/lifetime notes concern the return payload rather than the input, so it adds nothing new about parameters; baseline 3 applies.

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

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

States a specific verb and resource ('Open a live, interactive view of an Android device') and immediately scopes who it is for ('for the USER -- they see the screen and can tap, swipe, scroll and type'). It is clearly distinguishable from android_vnc_snapshot, which the description explicitly reserves for the agent looking at the screen 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?

Gives explicit routing: 'GIVE THE USER viewerUrl (or open it in the IDE's built-in browser)' for the interactive case, and 'To LOOK at the screen yourself, use android_vnc_snapshot' for the alternative. It even pre-empts a related tool's misuse by noting android_vnc_close 'has nothing to release'.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: the image is the exact frame VNC viewers receive, sourced from a shared capture (cheap, non-exclusive), and no VNC session must be open first. It does not mention cost limits or staleness, but adds substantive context beyond annotations.

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

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

Front-loaded with the core action and the return shape, then the coordinate-scaling caveat and the 'no VNC open needed' note. Every sentence carries information, though the em-dash/semicolon packing makes it slightly dense versus a cleaner multi-sentence form.

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 compensates by naming the returned JSON keys (width, height, imageWidth, imageHeight) and the critical scaling rule (multiply image positions by width/imageWidth). Combined with the coordinate linkage to device_tap, an agent has everything needed to call and interpret the result.

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

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

Only one parameter (udid), and schema coverage is 100% with its own description, so the schema carries the burden. The description does not elaborate on udid, instead spending its detail on the return payload's coordinate semantics — useful but not parameter semantics.

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

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

States a specific verb+resource ('returns the current screen as an image') plus the exact JSON payload fields. It also distinguishes itself from VNC-viewer infrastructure by noting it reads the device server's shared screen capture, so an agent can tell it apart from android_mjpeg_screenshot or device_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?

Clearly says it is 'cheap enough to call after every action' and that it 'Does not need android_vnc_open first' — an explicit prerequisite removal. It stops short of naming alternative screenshot siblings (device_screenshot, android_mjpeg_screenshot, android_video_stream) and when those would be preferred.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered without description help. The description adds that the deletion targets the server-side uploaded artifact rather than an installed app, but says nothing about behavior on a missing/invalid ID or whether re-deletion is a no-op.

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

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

Two sentences, zero filler, with the action stated first and the prerequisite second. 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 one-parameter destructive tool whose annotations carry the safety semantics, the description is nearly sufficient. It could still note behavior for missing IDs or whether only uploaded (not installed) artifacts are affected, but nothing critical for invocation is missing.

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

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

Schema description coverage is 100% and the single parameter is already documented as "File ID from app_list". The description merely restates that provenance, adding no new syntax, format, or validation detail, so the baseline of 3 applies.

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

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

States a specific verb (delete) and resource (an uploaded app file), scoped to the server. It is distinguishable from app_list/app_upload/app_install, though it does not explicitly contrast with the other delete-shaped siblings such as device_file_delete or device_uninstall_app.

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

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

The second sentence gives a concrete prerequisite routing step ("Use app_list to get the file ID"), which is useful. However, it never says when this tool is the right choice or when a sibling delete is preferable, so usage is only partially covered.

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

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

Annotations declare this is a non-read-only, non-idempotent, non-destructive operation, so the description carries less burden. The description adds platform-specific mechanics (APK/IPA installation methods), but it doesn't disclose prerequisites like device connectivity, potential side effects (e.g., overwriting existing app data), behavior on insufficient storage, or whether the install is silent or requires user interaction. This is a gap for a mutation tool with side effects.

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

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

The description is three short sentences, front-loaded with the core action and platform nuances, and ends with a crucial prerequisite. Every sentence earns its place with no wasted words.

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

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

For a two-parameter mutation tool with no output schema and low annotation coverage, the description is adequate but incomplete. It covers the basic action and prerequisite but omits behavioral details like error conditions, side effects, and return information, which an agent would need to invoke it correctly in an automation flow.

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

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

Schema description coverage is 100%, so both parameters (udid, appId) are already documented in the schema. The description adds a hint that appId comes from app_list, but that's also in the schema's parameter description. No additional syntax or format details are provided beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb+resource ('Install an uploaded app') and clarifies it works on a device, with platform-specific detail (APK via Android transport, IPA for iOS). It distinguishes itself from app_upload and app_list, though the cross-platform nature overlaps with ios_install_app, a sibling that is not mentioned.

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 explicitly tells the agent to 'Use app_list to get the file ID first', which provides a clear prerequisite and points to a sibling tool. However, it doesn't address when to use this multi-platform tool versus the platform-specific ios_install_app.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the 'current user' scoping constraint, which is genuinely useful behavioral context beyond the annotations, but nothing more (no pagination, ordering, or return shape).

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 waste. 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 zero-param read tool whose annotations and schema are fully covered, the description is minimally adequate. It does not state what is returned or whether results are paginated, and there is no output schema to fall back on, leaving a small gap.

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

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

Zero parameters, so there is nothing for the description to document; baseline for 0 params is 4. The 'current user' phrase appropriately clarifies the implicit scoping of the (absent) 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 (List) and resource (uploaded app files) scoped to the current user. It is clear on its own, though it doesn't differentiate from siblings like app_upload, app_delete, or app_install that share the 'app' namespace.

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 named, no prerequisites. The agent must infer from the name alone that this is the read-listing counterpart to app_upload/app_delete.

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: 50MB decoded-per-call cap, 0-based chunk ordering, that registration occurs only when the last chunk arrives, and that .ipa files are re-signed on the way in unless skipResign is true. Annotations only give safety hints; the description supplies the actual operational semantics.

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

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

Front-loads the purpose, then the chunking mechanics, the single-call shortcut, re-signing behavior, and return value in sequence. Every sentence carries distinct information with no filler.

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

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

For a complex chunked-upload mutation with no output schema, the description fully specifies size limits, chunk protocol, re-signing, and what the return value is (the id used by app_install and referenced as 'ra-app://<id>'). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the 3 baseline applies, but the description adds inter-parameter logic the schema does not — how chunkIndex/totalChunks must be paired, and that a sub-50MB file needs neither. This exceeds what the individual field descriptions convey.

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

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

States a specific verb and resource — 'Upload an app build (.apk/.ipa) to your App Library' — and clearly distinguishes this from sibling install/list/delete operations. An agent immediately knows this is the ingest step that precedes app_install.

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 establishes the workflow relationship ('Returns the id that app_install uses') and explains the single-call vs. chunked condition, which tells the agent when to supply chunkIndex/totalChunks. No explicit exclusions or when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description still adds real context beyond that: it 'only formats a URL', does not verify the run exists, and the path is relative and routed internally by the chat. It doesn't discuss any failure modes of a malformed sessionId, but that is a minor gap.

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

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

Front-loaded with the purpose, then usage, then the prerequisite caveat, which is a sound ordering. Four sentences plus a markdown example is slightly longer than this trivial formatting tool needs, but each sentence carries a distinct instruction.

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

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

There is no output schema, so the description appropriately supplies the return format ('Present the result as a markdown link', with a concrete example) and the routing behavior. Combined with the prerequisite check and the when-to-offer guidance, an agent has everything needed to call and present this tool correctly.

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

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

There is one parameter with 100% schema description coverage ('The run's session id'), so the schema already carries the semantics. The description implies the sessionId identifies a run but adds no format, sourcing, or validation detail beyond the schema, which is the baseline-3 case.

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

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

States a specific verb and resource ('Build a clickable link to a run's detail page') and immediately contrasts it with the sibling that fetches run data ('call automation_session_get first'), so an agent can tell it apart from automation_report or insights_build_link without opening a schema.

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

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

Explicitly says when to offer it ('after explaining a run so they can see the video, screenshots and full command list') and names the prerequisite/alternative path (call automation_session_get first if the run hasn't been fetched). Nothing about when-to-use is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavior beyond that: output is summarised and capped, limit returns the LAST n steps, failuresOnly can produce an empty list paired with a whyNoFailedSteps block on assertion failures, and each returned step carries error messages and locator provenance.

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

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

The description is front-loaded with the core verb and resource, then immediately identifies the tool as the debugging entry point. Despite being lengthy, each sentence carries actionable information about failure handling, step content, ongoing runs, follow-up tools, and output capping.

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 fully explains the return shape: ordered steps with duration and pass/fail, error messages on failed steps, locator/index data on element-scoped steps, empty-list semantics via whyNoFailedSteps, and partial results for ongoing runs. It also names the correct follow-up tool for per-step request/response details.

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

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

Schema description coverage is 100% and the schema already explains limit behavior, failuresOnly usage, and sessionId. The description reinforces the debugging use of failuresOnly and the filtered-view preference, but does not add parameter syntax or constraints beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Read the step-by-step command history of a run' with duration and pass/fail per step. It distinguishes itself from siblings by positioning itself as 'THE DEBUGGING TOOL' and pointing to automation_session_step, session_console_logs, and session_network_logs for follow-up.

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

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

It gives explicit when-to-use guidance ('to explain why a run failed'), alternatives ('use failuresOnly=true to land directly on the failing step'), and when-to-follow-up with sibling tools using the SAME session id. It also covers the ongoing-run case ('where has it got to?') and warns against re-fetching everything.

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 mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description adds substantial context beyond that: append-only semantics with no edit/delete, that the latest entry becomes the effectiveVerdict read back by other tools, and the ownership constraint where a foreign session reads as not found.

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

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

Front-loads the core action, then prerequisites, then parameter selection, then behavioral consequences. Dense but nearly every sentence carries unique, non-redundant information; slight length and backtick-heavy references keep it from a clean 5.

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

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

For a 5-param mutation tool with no output schema, it covers the full call path: prerequisite read, precondition on failureAnalysis.source, parameter selection per case, consequences (effectiveVerdict), and the ownership/permission boundary. An agent has everything needed 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 coverage is 100%, so baseline is 3, but the description adds relational meaning: failureKey's source path and omission rule for single-failure runs, the correct/incorrect dichotomy, and the conditional requirement of correctedCategory when verdict is incorrect. It reinforces rather than merely repeats the schema.

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

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

States a specific verb+resource: 'Record a verdict on one automatically-computed failure analysis'. It explicitly distinguishes its scope from the sibling read tools by stating it publishes feedback that automation_session_get / automation_report subsequently return, so an agent can tell it apart without opening a schema.

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

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

Gives an explicit precondition ('Call automation_session_get first — this only works on a run whose failureAnalysis.source is "recorded"'), explains the when-not case (lazily-analysed runs have nothing to give feedback on), and routes per-field usage (failureKey multiplicity, verdict=correct vs incorrect+correctedCategory).

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 a safe read operation; the description goes far beyond by explaining verdict/confidence semantics ("reported" vs "inferred"), stillRunning handling, the three failureAnalysis shapes (recorded/lazy/unavailable), reanalysisPending timing, and how source/effectiveVerdict should be interpreted. This is exactly the context an agent needs to interpret results correctly.

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

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

Purpose and the activation trigger are correctly front-loaded, but the body is one very dense multi-clause paragraph with no formatting, making the nested failureAnalysis variants hard to scan. Most sentences carry real information, so it is not padding, but the structure works against readability.

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

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

There is no output schema, so the description carries the full burden of describing return shape, and it does so thoroughly for every branch (recorded/lazy/unavailable analyses, stillRunning, reanalysisPending). Nothing an agent needs to call and interpret this tool is missing.

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

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

Only one parameter at 100% schema coverage, so the schema already documents sessionId and its origin (the /automation?session_id= link). The description adds no syntax, format, or validation detail beyond the schema, so the baseline 3 applies.

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

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

Specific verb (Read) and resource (one finished automation run), immediately enumerating what is returned: verdict, test, device/browser, capabilities, duration, video/snapshot presence. This distinguishes it cleanly from automation_sessions_list (plurals) and automation_session_step/commands (drill-downs).

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

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

Gives an explicit trigger ("START HERE when the user pastes a session id or an /automation?session_id=... link and asks what happened, why it failed, or how it went") and routes the agent to automation_session_feedback when a category is wrong. It also states the access boundary (only your own runs are readable).

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, idempotent profile, and the description layers on genuinely new behavioral facts: element-scoped steps arrive with an empty body and an opaque id that this tool resolves back to the findElement locator, and networkDuring explicitly reports when no traffic was captured rather than returning a misleading empty list.

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

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

Front-loaded with the core purpose and dense with useful detail, but the em-dash-heavy sentences run long and the element-resolution explanation could be tightened. Every sentence does earn its place, so it stops short of waste.

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

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

With no output schema, the description carries the burden of describing returns and does so thoroughly: bodies, status, timing, resolved locator, and correlated network requests. An agent has everything needed to call and interpret the result.

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

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

Schema description coverage is 100%, so all three parameters (sessionId, index, includeNetwork) are already documented in the schema, including the index semantics and the default-true network flag. The description adds only marginal semantics, mainly the browser-only scope of network correlation, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Open ONE step of a run') and enumerates exactly what is returned: request body, response body, status, timing, and the resolved locator. It is immediately distinguishable from automation_session_commands, which it names as the source of the index.

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

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

Explicitly prescribes the workflow: 'Use automation_session_commands first to get the step index, then come here for the step that matters.' It also states when the tool is the right answer ('which element?') and scopes the network behavior to browser runs only.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: it returns the new id and browse URL, defaults workItemType, and states that plain text gets wrapped in <p> tags. This is useful context beyond the structured fields, though it doesn't discuss failure modes or 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?

Four tight sentences, each earning its place, with the core action and the confirm-before-calling constraint front-loaded. No filler or restatement of the name.

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 compensates by stating the return value (new id + browse URL). Combined with the 100%-covered input schema and safety annotations, an agent has enough to invoke correctly; minor gaps remain (no mention of permission scope or tag behavior beyond schema).

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description's notes on the 'project' arg and on 'description' being plain text largely echo the schema, though the plain-text-to-HTML wrapping detail adds marginal value. Baseline 3 applies when the schema carries the load.

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 ('Create a new AzDO work item') and distinguishes itself from siblings azdo_get_work_item and azdo_search_work_items by being the creation path. An agent can tell what it does immediately.

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

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

Gives an explicit, non-optional usage rule ('ALWAYS confirm with the user before calling — this is a mutating operation'), which is strong guidance. It does not name an alternative tool or describe when to prefer creating vs. updating/searching, but the confirmation precondition is clear and actionable.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds real context: a 50-item cap, the return projection matching azdo_get_work_item minus links, and the non-obvious quirk that the SELECT clause is ignored except for IDs because the tool batch-fetches full fields.

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

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

Front-loaded with purpose, then return behavior, then syntax examples – a sensible order. The parenthetical asides are slightly dense but each sentence conveys distinct, useful information rather than restating the schema.

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

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

With no output schema, the description compensates by describing the return shape (up to 50 items, projection minus links). It covers the essentials for correct invocation; only pagination/auth details are left implicit, which the openWorld annotation partly signals.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds value by giving two concrete WIQL examples and clarifying that only the SELECT IDs are honored regardless of what fields are projected. This meaningfully augments the wiql parameter beyond its schema entry.

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

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

States a specific verb (Search) and resource (AzDO work items) plus the mechanism (WIQL), and anchors it against a familiar equivalent ('AzDO's equivalent of Jira's JQL'). It also implicitly distinguishes itself from azdo_get_work_item and azdo_create_work_item by naming the former for the structured link list.

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

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

Routes the agent to azdo_get_work_item when the structured links list is needed, and the schema reinforces narrowing WIQL for wider sweeps. It gives clear context for use but offers no exclusions (e.g., when to prefer jira_search or a non-WIQL path).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, destructiveHint=false. The description adds useful behavioral context beyond the annotations: it discloses the output shape ({ ok, packageName, apks: [{ path, sizeBytes, role }] }) and the downstream constraints (5MB default pull cap, 20MB max). It does not mention authentication or permission requirements, but for a read-only path listing that's minor.

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

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

Three sentences, front-loaded with the core action and mechanism, then behavior details, then return shape. No waste; every sentence adds distinct value.

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

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

No output schema exists, so the description compensates by fully specifying the return object. It covers the action, the split-APK nuance, downstream usage with device_file_pull, and size limits. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters (udid, packageName) have descriptions in the schema. The description mentions packageName implicitly through 'an installed app' but adds no additional semantics beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (List), a specific resource (APK file paths for an installed app), and notes the mechanism (`pm path`). The description also notes it returns base + split APKs, which clearly distinguishes it from device_list_apps (lists installed apps) and device_file_list (lists directory contents).

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

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

Explicitly tells the agent what to do with the results: "use device_file_pull on individual paths to fetch the bytes (default 5MB cap, raise via maxSizeBytes up to 20MB)". It names the alternative for a subsequent step but doesn't explicitly state when this tool should NOT be used (e.g., when you only want metadata vs. bytes). Clear context, no 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value by enumerating the returned data (level, charging state, temperature), which is meaningful behavioral context given no output schema exists.

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

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

One tightly written sentence, front-loaded with the verb and scope, with the parenthetical detail placed where it does not obstruct comprehension. Nothing is wasted.

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

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

For a simple single-parameter read tool with a full annotation set, this is nearly complete; the only gap is the absence of guidance about refresh/polling behavior, which is minor and not required.

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

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

Schema coverage is 100% and the single udid parameter is fully documented in the schema, so the baseline is 3. The description does not mention the udid requirement or add any format detail beyond what the schema provides.

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

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

States a specific verb and resource ('Get battery status') and scopes it to an Android device, which distinguishes it from the sibling ios_battery tool without opening either schema. It also names the returned fields (level, charging state, temperature), so the agent knows exactly what it retrieves.

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 prerequisites are stated. For a self-evident read-only status tool this is acceptable, but an agent gets no routing hint beyond the platform word 'Android'.

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 the key behavioral traits: destructiveHint=true, idempotentHint=true, readOnlyHint=false. The description reinforces which artifacts are destroyed (data + cache) but adds no auth requirements, running-state constraints, or irreversibility note beyond what annotations declare.

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

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

Two short sentences, zero filler, purpose front-loaded before the clarifying analogy. Nothing to trim.

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

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

For a two-param destructive tool with full annotation coverage and no output schema, the definition covers what it does and what it wipes, and idempotency/destructiveness come from annotations. Only minor gaps remain (device/app state prerequisites), which is why it falls just short of a 5 rather than failing completeness.

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

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

Schema coverage is 100% and both parameters are self-documented (UDID serial, package name with example). The description only confirms the target app, adding no new parameter semantics, so this sits at the baseline rather than above it.

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

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

Specific verb+resource: 'Clear all data and cache for an app on an Android device.' The Settings equivalence ('Clear Storage') anchors the meaning precisely. It is clearly distinguishable from siblings like device_terminate_app, device_uninstall_app, and device_clear_app_locale.

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 Settings analogy implies when to use it, but the description never states prerequisites (app should be installed/not running) nor routes the agent among close siblings such as device_terminate_app (stops process), device_uninstall_app (removes app), and device_clear_app_locale (narrower reset). Usage is inferable, not 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, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds value beyond them with a real precondition ('Requires Android 13+') and the post-condition (fallback to system language), though it does not state whether the app must be relaunched for the change to take effect.

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

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

Three short sentences with zero filler: effect first, then the sibling relationship, then the platform requirement. Every sentence carries information an agent needs and nothing is buried.

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

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

For a two-parameter, no-output-schema tool with rich annotations, the definition covers the effect, the alternative, and the OS floor. The one missing piece is whether the locale change takes effect immediately or only after relaunching the app.

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

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

Schema description coverage is 100%, so udid and packageName are already fully documented in the schema. The description says 'an Android app' without adding format or constraint detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb ('drop') and resource ('per-app locale override') plus the resulting state ('falls back to the device system language'), which makes the outcome unambiguous. It also names the counterpart tool, device_launch_app_in_language, so an agent can separate it from device_set_device_language and other locale siblings without opening a schema.

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

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

Naming device_launch_app_in_language as the counterpart gives a clear implied usage pattern: this is the undo/reset path after a per-app language was applied. It gives clear context but stops short of explicit when-not conditions (e.g. use device_set_device_language to change the whole device locale).

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, idempotentHint=true, openWorldHint=false, so the state-change profile is known. The description adds genuine context beyond that: the helper service stops pushing mocked fixes and apps fall back to the real GPS/network provider, explaining the observable consequence. It does not cover failure modes (no active mock, unknown UDID).

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

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

Two sentences, zero waste, with the core action front-loaded and the sibling reference placed where a routing agent will see it 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 single-parameter, annotation-rich tool with no output schema, the description supplies purpose, effect, and the sibling relationship. Only edge-case behavior (calling when no mock is active, error response) is left 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?

Only one parameter (udid) and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax or format detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb (Stop) plus resource (mock GPS) and scope (Android device), then explicitly names its counterpart device_set_location. An agent can distinguish it from device_set_location, device_get_location, and device_clear_app_data without opening any schema.

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

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

The counterpart framing to device_set_location clearly implies when to call it (after location mocking is no longer needed), and it implicitly routes the agent to device_set_location for the inverse action. No explicit when-not-to-use or prerequisite (e.g., mock must be active) is 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, idempotentHint=true and readOnlyHint=false. The description adds genuine context beyond those flags: the cursor is moved to the end, exactly N backspaces are sent based on the current text length, and the field must already be focused. It stops short of noting edge cases such as an empty field or non-text focused elements, so it is helpful but not exhaustive.

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

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

Two compact sentences, action and mechanism front-loaded, followed by the prerequisite and the alternative. No filler; every clause carries information.

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

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

For a destructive, non-readOnly mutation with no output schema, the description covers mechanism, prerequisite, and the preferred alternative path. It omits only minor edge behavior (e.g., clearing an already-empty field, non-text targets), which keeps it just short of fully complete.

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

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

There is a single parameter (udid) with 100% schema description coverage, so the schema carries the meaning and the description adds nothing about parameters. This matches the baseline 3 for high-coverage schemas.

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 ('Clear the focused text field on Android') and even explains the mechanism (reads text length, sends that many DELETE keycodes). It is impossible to confuse with device_type, which is named and distinguished explicitly.

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

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

It states the precondition ('Tap the field to focus it first') and routes to the alternative for the related case ('To clear and re-type in one call, use device_type with clearFirst:true instead'). Both the when and the when-not are 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 cover the read-only/idempotent safety profile, but the description adds critical behavior beyond them: on Android 13+ the OS blocks this path, so it returns an empty-clipboard sentinel rather than throwing 'No shell command implementation.' This is exactly the kind of failure-mode disclosure 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?

Purpose is front-loaded in the first sentence, followed by the platform constraint and the workaround. The sentences are dense but each carries information; minor verbosity in the 13+ explanation keeps it from a perfect score.

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

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

For a single-param read tool with no output schema, the description supplies the return behavior (empty sentinel vs error) and the platform caveat, so nothing an agent needs to call and interpret it correctly is missing.

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

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

Schema description coverage is 100% for the single udid parameter, so the schema already carries parameter meaning. The description adds no syntax or format detail beyond it, making the baseline 3 correct.

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

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

States a specific verb (read) and resource (clipboard content) scoped to an Android device, and implicitly contrasts with the sibling device_clipboard_set. An agent can distinguish it from other device_* tools 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?

Explicitly states when the tool works (Android 12 and earlier) and when it does not (Android 13+), and names the alternative (set via device_clipboard_set and paste directly). Both the condition and the recommended workaround are spelled out.

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

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

Annotations already cover the safety profile (idempotent, non-destructive, not read-only), and the description adds genuine behavioral context beyond them: the paste injection is built into the device control protocol rather than requiring a separate Ctrl+V, and an empty string clears the clipboard. It stops short of noting auth, device-state, or failure behavior.

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

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

Three short sentences, front-loaded with the core action, then the paste side effect, then the clearing edge case. Zero filler and no repetition of schema content beyond what reinforces behavior.

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

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

For a three-parameter setter with no output schema, the description covers the action, the notable side effect, and the edge case, which is nearly everything an agent needs. It could still mention required device state (unlocked/focused target for paste) to be fully self-sufficient.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema doesn't: paste triggers KEYCODE_PASTE 'immediately after' the set, and that this happens inside the control protocol. The empty-string-clears behavior duplicates the schema's content description but confirms the edge case.

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

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

States a specific verb and resource ('Set the Android device clipboard') along with the transport ('device control channel'), so the operation is unambiguous. It doesn't explicitly contrast itself with the obvious counterpart device_clipboard_get or the iOS ios_clipboard_set_hid, but the Android-specific scope is clear enough to disambiguate.

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: the agent learns that paste:true triggers an immediate KEYCODE_PASTE, which suggests the tool is for clipboard-then-paste workflows. There is no explicit when-to-use vs. alternatives guidance, no mention of prerequisites (device unlocked, focused field), and no pointer to device_clipboard_get for the read counterpart.

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, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds the return payload (package name and activity), which is useful given no output schema, but says nothing about failure modes on a non-Android or disconnected device.

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

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

Two short sentences, action first, return value second. No filler or repetition of the title.

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

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

For a simple single-parameter read tool with full annotation coverage, the description delivers purpose and return shape. The only minor omission is error behavior if the device is unavailable, which is marginal.

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?

One parameter with 100% schema description coverage, so the schema already documents udid as the device serial. The description adds nothing about the parameter, which is the expected baseline when the schema does the work.

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 ('Get the currently active (foreground) app') and scopes it to an Android device, which implicitly separates it from the iOS sibling ios_active_app. It stops short of explicitly naming that sibling, so it is clear but not fully differentiated in text.

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

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

No guidance on when to prefer this over alternatives such as device_list_apps, device_page_source, or ios_active_app. The Android qualifier is the only routing signal, and it is left for the agent to infer.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds real value beyond them: keycode 187 (APP_SWITCH) dispatch, a policy-gated shell, a UI settle wait, and the swipe-away sequence. It also sketches the return shape, which no output schema provides. It does not say what happens if the target card is absent, a minor gap.

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