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

With no annotations, the description carries the full burden and does most of it: it discloses that the call blocks and waits, that the user can override the buttons with free text, the three return shapes (ANSWER, ANSWER (typed), NO ANSWER), that marks are removed after answering, that DONE is prefixed when all marks are auto-detected complete, and that browser_highlight opens full screen and closes afterward. Remaining gaps are timeout/no-answer timing and what happens if the user dismisses the bubble, which the description leaves unspecified.

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 primary use case, and every sentence carries behavioral information rather than filler. It is dense and parenthetical-heavy, with long compound sentences, but nothing is clearly expendable.

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

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

For a no-annotation, no-output-schema tool with 4 params, the description covers the return values, the blocking behavior, the two highlighting modes, and the confirm hand-off — everything an agent needs to call it correctly 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%, so baseline is 3, but the description adds real value beyond the schema: it explains that browser_highlight is used "instead of highlight" (mutual exclusivity not expressible in JSON Schema), that highlight marks make the question avoid covering the screen, and that marks auto-clear plus trigger the DONE result. It does not add format guidance for question/options 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?

"Ask the user a question in the Buddy bubble and wait for the answer" gives a specific verb, resource, and interaction model (blocking UI prompt) that no sibling shares. It also explicitly distinguishes itself from confirm ("it is not an approval") and from point_out (highlight is described as carrying point_out semantics).

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

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

States the triggering condition explicitly ("when you need the user to choose or decide ... instead of guessing") and names the alternative for the approval case ("still call confirm before anything outward-facing"). The hand-over-to-user pattern with highlight is scoped with a concrete example and result shape.

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

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

With no annotations to lean on, the description carries the behavioral burden well: it discloses the unsaved-changes guard ('Buddy stays the first time and says so'), the return value (current tab location or a no-previous-page signal), and the natural follow-up call. An agent knows the tool may not actually navigate on the first attempt, which is non-obvious and critical to correct handling.

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

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

The core action is front-loaded in the first clause and the subsequent sentences cover the edge case and the return/follow-up. The phrase 'like a browser's back button' slightly restates the verb, but everything else earns its place.

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

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

No output schema exists, and the description compensates by stating what is returned and what the failure mode looks like. For a zero-argument, annotation-free navigation tool, 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The text correctly implies no arguments are needed, matching the empty 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?

Uses a specific verb (navigate back) on a specific resource (the current tab of the background browser) and anchors it to a familiar mental model (a browser's back button). This clearly distinguishes it from siblings like browser_open, browser_tabs, and browser_read, which open, list, or read rather than navigate history.

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 browser-navigation context is clear and the description explicitly sequences the next action: 'then call browser_read' once the move completes. It does not name an alternative for the no-history case (e.g., what to do if there is no previous page beyond being told so), 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?

No annotations, so the description carries the full behavioral burden. It does not say what happens after the click (navigation, form submit, page reload), whether refs go stale after a click, or what error is returned for an invalid/outdated ref.

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 action, the target, the identifier source, and examples all fit in one line.

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?

Adequate for a one-param tool with full schema coverage and no output schema, but for a browser-automation click it omits post-click effects and ref-staleness, which an agent needs to sequence calls 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 already labels 'ref' as 'The item's number'. The description adds genuine value by naming the source of that number (browser_read), which the schema does not 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?

Specific verb ('Tap') plus resource ('an item on the page') and a concrete enumeration of element kinds (link, button, checkbox). The reference to browser_read distinguishes it from browser_type/browser_scroll and from the native 'tap' sibling, though the native-vs-browser split 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?

States the prerequisite workflow clearly: the ref must be 'its number from browser_read'. That tells the agent to read first, then click. No guidance on when not to use it (e.g., versus 'tap' for native UI, or 'press'/'confirm').

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

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

With no annotations, the description must carry the load, and it does disclose useful traits: separate background browser, visible to the user in chat, does not consume the phone's screen, and returns page text like browser_read. It omits failure behavior, timeouts, and whether navigation state or tabs persist beyond the new_tab flag.

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

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

Two short sentences with the key distinguishing fact (background browser, not the phone screen) front-loaded, and the return behavior stated immediately after. The parenthetical is slightly awkward but carries real 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 simple 2-parameter navigation tool with no output schema, the description covers what the agent needs: where the page opens, that the user can see it, and that the response is page text. Missing only edge-case behavior such as navigation errors.

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

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

Schema coverage is 100%, so both url and new_tab are already well documented in the schema; baseline 3 applies. The description adds no extra semantics for new_tab or URL validation beyond what the schema states.

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 (Open) and resource (a web page) plus the distinctive setting: Buddy's background browser, which is separate from the phone's screen. This implicitly separates it from open_url and read_screen, though it never names those siblings explicitly.

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

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

Usage is only implied: 'background browser ... separate browser the user can watch' hints at when to prefer this over a phone-screen tool, but there is no explicit when-to-use, when-not-to-use, or named alternative such as open_url or browser_read.

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

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

With no annotations, the description carries the full burden and does well: it discloses text-only output, the [n] item numbering, the critical invariant that numbers stay valid only until the page changes, and paginated reads for long pages. It does not state permissions or whether reads have side effects, but for a read tool the disclosed traits are the operationally important ones.

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, zero filler, with the core action front-loaded and the numbering convention and pagination rule following in priority order.

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

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

With no output schema, the description wisely explains the return shape (numbered text items, multi-part output) rather than leaving it opaque. Minor gap: it doesn't say where the 'previous part's note' appears in the response, though the schema points to it.

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

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

Schema coverage is 100% and the single 'from' parameter is already documented as a character offset taken from the previous part. The description reinforces pagination ('Long pages come in parts: pass from to read on') but adds no syntax or sourcing detail beyond the schema.

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

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

States a specific verb and resource (read the page in the background browser) and specifies the output form (text). 'Background browser' implicitly distinguishes it from read_screen, but no sibling is named explicitly.

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

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

The numbering scheme implies the tool is a precursor to browser_click/tap, but the description never says when to use this instead of read_screen, browser_screenshot, or screenshot, nor when not to use it.

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

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

No annotations at all, so the description carries the full burden. It does disclose the key behavioral trait that the capture is of the background browser rather than the current foreground screen, but it says nothing about needing an open browser/tab, failure behavior, viewport vs full page, or whether the call perturbs page state.

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

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

One sentence with no filler, and the core purpose plus the routing condition are front-loaded. The phrasing 'A picture of what the background browser shows' is slightly indirect compared to simply saying it captures the browser view.

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

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

For a zero-parameter, annotation-free tool with no output schema, the description covers what it produces and when to choose it. The remaining gap — prerequisites like an active browser session and capture scope — is modest but real.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. No parameter semantics are needed or missing.

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

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

States a concrete verb+resource: a picture of what the background browser shows. It distinguishes itself from browser_read by targeting content that tool can't describe (images, maps, layouts), though it never distinguishes itself from the plain `screenshot` sibling.

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

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

Gives an explicit selection condition: use this when browser_read can't describe the content — images, maps, or layouts. It lacks any when-not guidance or comparison against the sibling `screenshot` (full device) and `read_screen`, which an agent must otherwise 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?

With no annotations, the description carries the full burden and does disclose a side effect (triggering more content to load) and that it acts on the background browser rather than the visible screen. It does not say how far it scrolls per call, whether it waits for the load to settle, or what happens if no browser session is active.

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

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

One sentence, zero filler, with the action front-loaded and the useful caveat in a compact parenthetical.

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

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

For an unannotated browser-mutation tool with no output schema, the definition covers what it does and one behavioral consequence, but leaves open scroll granularity, whether new content is returned or must be re-read via `browser_read`, and error conditions.

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

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

Schema coverage is 0%, but the single parameter is a two-value enum (down/up) whose meaning is self-evident. The description mentions neither `direction` nor scroll distance, so it adds nothing beyond the schema — however little is needed here.

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 ("scroll the page in the background browser") and scopes it to the browser rather than the foreground screen, which implicitly separates it from the generic `scroll`/`swipe` siblings. It does not name those siblings outright, so differentiation is inferable rather than explicit.

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

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

The parenthetical "(loads more on endless pages)" hints at the trigger condition — use it to pull in lazily loaded content — but there is no explicit when-not guidance or named alternative for ordinary page scrolling.

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

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

With no annotations, the description carries the load and discloses real behavior: the no-arg return format (numbered lines with title and address, current tab marked) and the side effect that browser_* tools follow the current tab. It omits what closing a tab does to the conversation/page state or what happens on an invalid tab number.

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

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

Dense and front-loaded: the resource and its three modes come first, prerequisites last. The nested parentheticals make it slightly run-on, but no sentence is wasted.

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

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

For a two-optional-param tool with no output schema and no annotations, it covers invocation modes, tab provenance, and the listing output. Remaining gaps (error behavior for bad indices, state after closing the current tab) are modest.

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 already say "Number of the tab ... from the list." The description adds the missing linkage by explaining that the no-arg listing produces those numbers, so the agent knows how to obtain valid values.

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

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

States a specific verb and resource ("Manage the background browser's tabs") and enumerates its three modes: list, switch_to, close. It also names how tabs come into existence (browser_open new_tab), which separates it from the sibling browser_open.

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 maps each call shape to an outcome: no arguments lists tabs, switch_to makes a tab current, close closes it. It also warns that the other browser_* tools act on the current tab, which tells the agent when switching is a prerequisite for other calls.

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

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

With no annotations, the description carries the burden: it usefully discloses that text is replaced by default unless append is true and that submit presses Enter. It does not say whether the element is scrolled into view, whether focus is required, what happens if ref is stale, or what the tool returns on failure.

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

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

A single tightly-packed sentence with a parenthetical handles the append default up front and finishes with the submit behavior. Nothing is wasted, though the dual typing/select mode is slightly buried mid-sentence.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the description covers the core semantics but leaves out error/failure behavior and post-action state, which an agent would want before calling it in a live browser session.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: ref is specifically the number produced by browser_read, text is overloaded to mean either typed text or the option label for a select, and append/submit are framed as behavior toggles rather than bare flags.

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

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

States a concrete verb (type) and resource (text field / select), and clarifies that the target is identified by the number returned from browser_read. It distinguishes two modes (typing into a field vs. picking a select option), but never mentions how it differs from the sibling type_text or browser_click.

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 usage context by tying ref to browser_read, and explains when append applies. However, it gives no explicit 'use this instead of type_text/browser_click' routing guidance, so an agent must infer which tool to pick for browser vs. non-browser input.

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

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

No annotations are provided, and the description carries the full burden well: it discloses that the call blocks and waits, enumerates the three possible verdicts (APPROVED, DENIED, CHANGES REQUESTED), and describes the revise-and-reconfirm loop. The only minor omission is timeout or failure behavior, which does not undermine the core behavioral picture.

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

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

Front-loaded with the core action, then the requirement condition, then the return values and loop. Every sentence earns its place, though the final sentence is a run-on that packs the return enum and the retry instruction together and could be split for faster parsing.

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

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

With no output schema and no annotations, the description correctly takes on the return-value explanation and the mandatory-usage rule. It is nearly complete for a single-parameter tool; only the behavior on timeout, user dismissal, or no response is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real guidance beyond the schema: 'Show the exact text or action' tells the agent what content the summary must contain, which is a quality constraint the schema's own wording only partially implies.

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 mechanism: ask the user to approve an action in the Buddy bubble and wait for the answer. It is clearly distinguishable from siblings like 'ask' and 'notify' because it is framed as a blocking approval gate returning a verdict.

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 enumerates the triggering conditions ('REQUIRED before sending messages, posting, buying, deleting, or changing settings') and gives the required follow-up path for CHANGES REQUESTED. An agent knows both when to call it and what to do with each outcome without inference.

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

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

With no annotations, the description carries the burden and does important work: it warns that 'the user taps Install/Update themselves,' so the agent understands this is an installer-launch, not an automated install. It doesn't cover permission requirements, error behavior, or what open_url/tap could do instead.

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

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

Two compact sentences front-load the action and follow with input formats and the required follow-up. Slightly dense with parentheticals, but every clause adds actionable information.

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

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

For a one-parameter tool with no output schema and no annotations, the description covers the key facts an agent needs: accepted path forms, the fact that the user completes the install, and the next tool to call. Minor gaps remain around failure modes and permissions.

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

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

Schema coverage is 100% and the schema's path description already covers both Linux paths and localhost URLs. The description adds concrete example paths (e.g. /root/.buddy/work/myapp/build/app.apk, Termux port) which give useful flavor but no additional constraint semantics beyond the schema.

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

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

States a specific verb and resource: 'Open Android's installer for an APK built in Buddy's Linux' or served locally. This clearly separates it from siblings like open_app or open_url by tying it to the APK install flow.

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 two supported input situations (a built path or a localhost URL) and explicitly directs the agent to call wait_for_install next. It doesn't spell out when-not-to-use or failure cases, keeping it at a clear but not exhaustive 4.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read-only operation and the scope is limited to launchable apps, but it does not explicitly state side effects, permissions, or safety characteristics.

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

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

The description is a single front-loaded sentence with no wasted words. It states the resource and the key returned field 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 simple zero-parameter listing tool with no output schema, the description is mostly complete: it states what is listed and that package names are included. It does not describe ordering, filtering, or exact return structure, but those gaps are minor for this tool's complexity.

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

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

The tool takes zero parameters, so parameter semantics are not a meaningful source of complexity. The baseline score for no parameters is 4.

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 pair: 'List launchable apps' and adds that package names are included. This clearly distinguishes it from action-oriented siblings like open_app and install_apk, though it does not explicitly name those alternatives.

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

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

The purpose implies this is used to discover available apps before calling open_app, but there is no explicit when-to-use or when-not-to-use guidance. For a zero-parameter listing tool the intended usage is strongly implied, but not 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?

With no annotations, the description carries the full burden and does so: it discloses the hold duration (~0.7 s), the target resolution rule tied to read_screen, the return value ('Long-pressed' plus location), and the required follow-up (call read_screen to see the opened menu). That is a rich behavioral profile for a UI interaction 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 action and duration, followed by usage and then the return/follow-up. Every sentence adds distinct value with no repetition.

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

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

There is no output schema, and the description compensates by stating the return value and the natural next step (read_screen). For a three-parameter, annotation-free interaction tool, nothing an agent needs in order 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 description coverage is 100%, so the schema already explains x, y, and element. The description restates the element-vs-coordinate alternative and adds the 'from the last read_screen' provenance hint, but provides no additional syntax or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('press and hold an element or screen coordinate') with the timing (about 0.7 s), and explicitly distinguishes itself from tap. An agent can tell exactly what this does versus the sibling tap/press 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?

Names concrete use cases (message/item menus, selecting items or text, moving icons) and routes normal taps to the tap tool. It also says which target form to supply (element id from the last read_screen, or x/y pixels), leaving little to inference.

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

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

With no annotations at all, the description carries the full burden, and it does disclose the most important trait: the call returns immediately without halting the workflow. It does not say whether the bubble text replaces prior status text, how long it persists, or whether it fails silently — meaningful gaps for a UI-mutation tool with zero annotation coverage.

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

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

One sentence, no filler, with the effect stated first and the key behavioral qualifier ('without stopping') tacked on where it is most useful. 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 one-parameter tool with no output schema and no annotations, the description covers the essentials: what is shown, where, and that it is non-blocking. Only the lifecycle details (persistence, overwrite behavior) are missing, which is a modest gap 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?

There is a single parameter at 100% schema description coverage ('Status text'), so the schema already does the heavy lifting and baseline 3 applies. The description adds only a weak hint that the text should be short, with no format, length, or content guidance beyond that word.

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 verb 'Show' plus the resource 'a short status line in the Buddy bubble' makes the effect concrete — the agent knows this writes transient UI text rather than performing an action. It is distinguishable from siblings like ask or confirm via 'without stopping', but it never names or contrasts those siblings explicitly.

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

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

'Without stopping' implies a non-blocking status update, which lets an agent infer it should be preferred over ask/confirm when no user response is needed. However, no explicit when-to-use or when-not-to-use guidance is given, and the near-neighbor update_buddy is never mentioned, so the routing decision 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?

No annotations are provided, so the description carries the full burden. The 'installed' qualifier does hint at a precondition (it will fail on uninstalled apps), but the description says nothing about foregrounding behavior, permission prompts, or failure modes.

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

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

One short front-loaded sentence with the accepted input forms grouped inline as an example. Nothing is wasted and nothing essential 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 one-parameter tool this is close to sufficient, but with no output schema an agent cannot learn what a successful call returns or how failure (app not installed) surfaces. A clause covering that would complete it.

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

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

Schema description coverage is 100% and the schema already states 'App name or package', so the description only adds the concrete example 'Messenger'. That helps but is marginal against a fully documented single parameter, so the baseline 3 applies.

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

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

States a clear verb+resource ('Open an installed app') with two accepted identifier forms, and the word 'installed' implicitly separates it from install_apk and list_apps. It never names a sibling explicitly, so differentiation is inferential rather than stated.

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

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

Usage is implied by the verb — launch something already on the device — but there is no explicit when-to-use, no pointer to list_apps for discovering names, and no statement of what to do when install_apk is the right prior step.

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

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

With no annotations, the description carries the full burden and does well: it discloses the screen-takeover side effect, states that nothing is sent or called by opening a link, gives the return value ('Opened'), and tells the agent to call read_screen to observe the result. It doesn't cover failure modes (no handler installed, bad URL), which is the only meaningful gap.

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

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

Front-loaded with the action and its core semantics, then alternatives, then the side-effect caveat, then the follow-up. It's a single dense paragraph with heavy parentheticals (the consumer-app examples), which costs a little readability but every sentence 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?

A one-parameter, no-output-schema tool whose description still covers the action semantics, the scheme routing matrix, the side-effect profile, the return value, and the follow-up call. Nothing an agent needs in order 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 baseline is 3, but the description adds real meaning beyond the schema's single 'tel:' example by enumerating handler families — https, mailto, tel, geo/maps, market:// — so the agent knows which schemes are legitimately routable rather than only the accepted type.

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

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

States a specific verb and resource ('Open a link on the phone') and immediately defines the exact semantics — behaving as a tap would, with https links routed to the browser/handler app and deep-link schemes routed to their apps. It explicitly contrasts itself with the browser_* family, so an agent can distinguish it from browser_open without opening either schema.

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

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

Gives an explicit when-not rule: 'For public web pages you only need to read, the browser_* tools work without taking over the screen.' That names the alternative and the condition that selects it, which is exactly the routing decision 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?

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: marks turn green and disappear when the user acts, wait=true blocks until DONE/GONE/LEFT/NOT DONE with those exact return states, marks follow scrolling elements and vanish on app changes or other phone actions, and a no-marks call removes them. This is unusually rich behavioral disclosure for an unannotated 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 description is front-loaded with the core action and mechanism, then layers in behavior. It is long but dense, with each clause carrying real information (return states, lifetime, scrolling behavior). It is somewhat run-on and could be broken into shorter sentences for readability, but no sentence is filler.

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

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

For a tool with no annotations, no output schema, and four parameters, the description supplies what an agent needs: what it draws, how it behaves over time, what wait returns, how marks are removed, and when they disappear. Nothing essential to calling it correctly appears 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 75%, so the schema already documents most parameters; the description adds meaningful semantics for wait=true (blocking until DONE or GONE/LEFT/NOT DONE) that go beyond the schema's brief text. It also clarifies the removal semantics of an empty marks call, though it adds little extra detail for x/y/element beyond the schema descriptions.

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

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

The description gives a specific verb ('Show the user where to look or what to do') and a concrete mechanism ('a box, circle or arrow with a short label around up to 6 elements, drawn over the app without blocking their touches'). It clearly distinguishes itself from action tools like tap by framing the marks as guidance 'instead of doing it for 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 explicitly states the intended use case ('guide the user step by step through something they want to learn to do themselves, one step per call, instead of doing it for them') and even covers the removal case ('Call with no marks to remove them'). It does not name a specific sibling tool like tap or notify as the alternative, but it does describe the contrasting behavior.

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

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

With no annotations, the description carries the burden and does disclose the return contract ('Pressed' or 'Could not press'), which usefully signals that failure is possible and confirmation is weak. It does not state prerequisites (accessibility service, screen state) or whether back can discard unsaved state, leaving some behavioral gaps.

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

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

One dense sentence of value definitions, one routing hint, one return-value note. Every clause earns its place and the core action is front-loaded.

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

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

A single-parameter tool with no output schema; the description supplies value semantics, an alternative route, and the return strings an agent needs to interpret results. Nothing material is missing.

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

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

Schema coverage is 0% and the schema only lists bare enum strings, so the description must compensate — and it does, defining the real-world effect of every one of the five values rather than repeating the enum tokens.

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 (press) plus resource (Android system buttons) with all five button values enumerated and explained in plain language. An agent can distinguish it from long_press, tap, and scroll from the text alone.

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

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

Each button value carries its own when-to-use gloss (back closes dialogs/keyboard, home goes to home screen, etc.), and it explicitly names an alternative and the condition that selects it: 'To switch apps, open_app is faster than home and recents.'

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

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

No annotations exist, so the description carries the full behavioral burden, and it delivers the single most important non-obvious trait: 'Element ids are only valid until the next read_screen', which warns the agent that ids are ephemeral and must be re-read before acting. It does not cover failure modes (e.g., screen not ready, foreground app changes) or latency, which keeps it out of 5 territory.

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, each earning its place: what it returns, when to call it, and the id-staleness caveat. The most actionable information (when to call) is front-loaded right after the purpose statement, 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 zero-parameter tool with no output schema, the description adequately conveys the return shape (elements with ids, text, coordinates) and the core workflow contract. It is slightly incomplete in not mentioning error/empty states or whether offscreen elements are included (requiring a scroll), which an agent would eventually need.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The schema is empty and fully described, and no misleading parameter hints are given.

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

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

States a specific verb and resource ('Read what is on the phone screen') and immediately characterizes the return shape as 'a list of UI elements with ids, text, and tap coordinates'. This implicitly and effectively distinguishes it from the sibling 'screenshot' (pixels) and 'browser_read' (web DOM) by naming the structured-element output.

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 invocation guidance: 'Call this first and after every action to see the result.' That is a clear, prescriptive workflow rule an agent can follow directly. It stops short of a 5 because no alternative is named (e.g., when to prefer 'screenshot' or 'browser_read') and no when-not condition is stated.

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

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

With no annotations, the description carries the burden well: it discloses that this is a mutating reply, that it avoids opening the app, and that Buddy shows the user an approval card with the text first unless confirm was just called. It stops short of describing failure modes or what happens if the reply cannot be delivered, keeping it from a 5.

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

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

Three sentences, front-loaded with the action and immediately followed by preconditions and the approval caveat. Dense but every clause earns its place; the 'unless you called confirm' caveat is essential context rather than padding.

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

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

For a single-parameter, no-output-schema, no-annotation tool, the description covers purpose, preconditions, the approval flow, and the confirm interaction. It is largely complete; only edge-case failure behavior is left unspecified, which is minor here.

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 'text' is clearly documented as 'The reply, exactly as it should be sent.' The description references 'the text' shown on the approval card but adds no format or syntax 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?

The description states a specific verb+resource: it answers the notification that started the chat via the notification's own reply field, and clarifies it does so 'without opening the app.' An agent can distinguish this from general messaging or app interaction siblings instantly.

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 preconditions: 'Only in chats started by one of the user's notification rules, when the notification has a reply field,' and it names the alternative workflow ('unless you called confirm with it just before'). Both when-to-use and when-the-approval-is-skipped are 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?

With no annotations present, the description carries the full burden and does real work: it discloses the return format (JPEG) and that the reply includes instructions for converting image coordinates to screen pixels, which directly enables follow-up tap/swipe calls. It omits capture scope (full screen vs. window) and any latency or permission considerations.

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 format, followed by the selection rule. Every clause carries information an agent needs; 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 parameterless, annotation-free tool with no output schema, the description covers what matters most: what is returned and how to use the coordinates afterward. Missing is the capture scope and the distinction from browser_screenshot, which would make it 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?

The tool takes zero parameters, so there is no parameter semantics to explain and nothing the description needs to compensate for. Baseline of 4 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 ("Take a screenshot") plus the output format (JPEG), which an agent can act on immediately. It differentiates from read_screen, but says nothing about how it differs from the sibling browser_screenshot, leaving one plausible ambiguity unresolved.

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

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

Gives an explicit when-to-use condition ("only when read_screen is not enough") with concrete examples (images, games, canvas UIs) and names the alternative tool. It stops short of an exclusion against browser_screenshot, so the routing guidance is strong but not exhaustive.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses the approximate scroll distance, default behavior without an element, targeted behavior with an element, return value ('Scrolled'), and a follow-up action. It does not mention edge cases such as reaching the end of a list or failure behavior, which keeps it from a 5.

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

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

The description is front-loaded with the core action and amount, then covers directions, element behavior, return value, and the swipe alternative in a compact paragraph. Every clause contributes useful guidance without repetition.

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 no annotations and no output schema, the description supplies the necessary behavioral context: how far it scrolls, how element targeting works, what it returns, and the recommended follow-up. It lacks only minor edge-case behavior, such as what happens at the end of a scrollable area.

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

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

Schema coverage is only 50%, but the description fully compensates: it explains each direction's meaning ('down' shows further down, 'up' goes back, 'left'/'right' for carousels and tabs) and clarifies that element is an optional scrollable element id from read_screen, including what happens when it is 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?

The description states a specific verb and resource ('Scroll a list or page'), specifies the scroll amount ('about a third of its height or width'), and explains the intended outcome ('reach content that isn't on screen yet'). It also distinguishes the four directions and hints at scope via the element parameter.

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 covers when to use the tool for page/list scrolling versus 'swipe' for precise dragging, and says to call read_screen afterward to see results. It also clarifies the behavior with and without an element id, leaving little ambiguity about invocation context.

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

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

No annotations are provided, so the description carries the full burden, and it does well: it discloses the short-swipe-becomes-tap behavior, the literal return value ('Swiped'), and that read_screen is needed to observe the effect. It omits any notes on failure cases or coordinate bounds, keeping it just short of a 5.

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

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

Three sentences, front-loaded with the core action, then usage, then return/follow-up. 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?

With no output schema, the description compensates by stating the return value ('Swiped') and the follow-up (read_screen). Coordinates, duration, edge cases, and alternatives are all covered, so nothing needed 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% and each parameter is already documented, including the duration_ms slow-drag/fast-fling semantics. The description reinforces the pixel coordinate meaning but adds no syntax or semantics beyond the schema, so baseline 3 is correct.

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

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

States a specific verb and resource — drag a finger from (x1,y1) to (x2,y2) in screen pixels — and positions it against siblings ('gestures scroll doesn't cover'), so an agent can differentiate it from scroll, tap, and long_press.

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?

Enumerates concrete when-to-use cases (slider, swipe a card/message aside, pull-to-refresh, map drag) and adds the edge case that a very short swipe counts as a tap, implicitly routing toward tap. Explicit context and exclusions are present.

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

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

With no annotations present, the description must carry the behavioral load; it does disclose that element ids are only valid relative to the last read_screen (a staleness constraint) and that coordinates are in screen pixels. It says nothing about what happens after the tap (navigation/UI change), failure modes for invalid ids, or timing, which would matter for an interaction tool.

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

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

One front-loaded sentence that names the action and both targeting modes with zero filler. Nothing is buried 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 simple, zero-required-param interaction tool this covers the essentials, but with no output schema and no annotations the description leaves open what a tap returns (success/failure), whether it awaits a UI transition, and how conflicting element + coordinate inputs are resolved.

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

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

Schema coverage is 100%, so all three parameters are already documented with units and provenance in the schema itself. The description restates the same semantics (element id source, pixels) without adding new meaning such as precedence when both element and x/y are supplied, which remains undefined.

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 ("Tap") and both accepted targets — an element id or pixel coordinates — so the resource and input modes are unambiguous. It stops short of differentiating itself from close siblings like long_press, swipe, or press, which an agent could confuse with a plain tap.

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 "by id from the last read_screen" implies the workflow prerequisite (read the screen first) and signals the two alternative targeting modes. There is no explicit when-not guidance, e.g. that long_press should be used for hold gestures or that coordinates are the fallback when elements aren't exposed.

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

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

With no annotations, the description carries the burden and does disclose the key destructive trait: content is replaced unless append is true, and submit triggers an enter/send action. It omits failure behavior (e.g., no focused field, invalid element id) and any confirmation of what the result looks like.

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

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

Three short sentences with zero filler, and the default behavior (replace) is front-loaded ahead of the modifiers. Every sentence conveys information the 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?

For a 4-parameter UI input tool with no annotations and no output schema, the description covers target selection, replacement semantics, and the submit side effect, which is close to enough. Missing only error/edge-case behavior for locating a field.

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

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

Schema description coverage is 100%, so all four parameters are already documented at the structured level, setting a baseline of 3. The prose restates append and submit meaning but adds no syntax, ordering, 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?

States a specific verb and target: "Type into the focused text field (or the given element)", which tells an agent exactly what the tool does. It does not explicitly differentiate itself from the sibling browser_type, leaving the web-vs-native context boundary to inference.

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

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

It implies the usage context (focused field, or supply an element id) and explains the append/submit modifiers, but never says when to prefer it over browser_type or what to do if no field is focused. No exclusions or alternatives 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?

With no annotations, the description carries the behavioral burden and discloses the key mutation: with install=true it downloads the update and opens Android's installer. It also states the user-confirmation constraint, but it does not cover network access, failure modes, or what happens when no update 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?

The description is compact and front-loaded: it begins with the core check behavior, then explains install=true, then gives usage guidance. Every clause adds relevant information without redundancy.

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

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

For a one-parameter tool with no output schema, the description covers the essential call behavior, install side effect, usage context, and user-confirmation boundary. It could be more complete by describing the check result or no-update behavior, but it is broadly 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% and the install parameter already describes true behavior, so the baseline is 3. The description adds useful default-mode meaning by implying that without install=true the tool only checks for an update and reports what's new.

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

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

The description states a specific verb and resource: checking for a newer official GitHub release of Buddy and optionally downloading/opening Android's installer. It is clear and actionable, but it does not explicitly distinguish itself from nearby tools like install_apk or wait_for_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 gives a clear usage trigger: use when the user asks to update Buddy or asks whether a newer version exists. It also adds an important constraint that only the user can tap Update, though it does not name alternative tools or when not to use this one.

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

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

With no annotations, the description carries the full burden. It discloses the important detail that the wait is capped at 10000 ms (implying early return once the UI settles), but does not say whether it blocks the caller, what happens if ms exceeds the cap, or whether the tool actually polls the UI versus sleeping blindly.

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

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

A single short sentence with zero filler, and the operative concept (waiting for UI settle) is front-loaded with the constraint trailing. 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 one-parameter, non-destructive tool this is close to adequate, but two things an agent would want are missing: what 'settle' is actually detected by, and what the tool returns or does on timeout (no output schema exists, so the description could have covered it).

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

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

Schema coverage is 100% and the schema already documents ms as 'Milliseconds', so the baseline is 3. The description goes beyond the schema by establishing the effective upper bound ('up to 10000 ms'), which is real semantic information an agent cannot get from the schema alone.

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 effect: 'Wait for the UI to settle', which tells an agent this is a delay/synchronization primitive rather than an observation tool. It is not explicitly differentiated from the adjacent siblings (read_screen, wait_for_install), but the purpose is unambiguous on its own.

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

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

The phrase 'for the UI to settle' implies the use case (pausing after an action before reading or tapping), but there is no explicit when-to-use/when-not guidance and no mention of wait_for_install as the alternative for install-related waiting. Usage must be inferred from the siblings list.

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

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

With no annotations, the description carries the behavioral burden and does well: it explains blocking behavior, success return, early exit if the installer is gone, and timeout behavior. It does not specify what happens on timeout (error vs. return value) or whether the tool interacts with the UI.

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

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

Three compact sentences, front-loaded with the precondition and followed by return conditions and the alternative to polling. No wasted wording.

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

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

Complete enough for a simple wait tool with full parameter documentation and no output schema. The main remaining gap is the exact result or failure behavior after the timeout expires.

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 three parameters. The description reinforces min_version_code and timeout semantics but adds little 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: waits for an APK installation to complete after the Android installer is opened. The scope is precise enough to distinguish it from generic wait, confirm, and install_apk siblings.

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

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

Clearly states when to use it: after opening the Android installer and before relying on shell polling loops. It names an alternative approach, though it does not explicitly list sibling tools or when not to use it.

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