Shipvo

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

With no annotations, the description carries the full disclosure burden, yet it only implies a state-changing navigation. It does not say what happens when there is no back stack to pop (error, no-op, or app exit), whether the action affects only the given session, or whether any permissions or valid-session preconditions apply.

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 five-word sentence with the action front-loaded and no filler. It is efficient, though the extreme brevity borders on under-specification for a stateful device action.

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

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

The tool has one required parameter, no output schema, and no annotations, so the description is the only source of behavioral detail; it provides none. An agent cannot tell how failures, empty history, or session scoping behave, which is material for a navigation command in a device-control suite.

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 session parameter is documented as coming from open_app, so the schema already does the work. The description adds no further meaning about the parameter, which meets 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?

'Go back one screen' states a concrete navigation action with a clear verb and unit of navigation, which is immediately distinguishable from sibling device actions like tap, scroll, and type. It stops short of naming or contrasting an alternative, but the action itself is unambiguous.

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

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

The description gives no conditions for when to use this instead of alternatives such as tapping an in-app back button or reopening the app via open_app. There is also no mention of prerequisites, such as a prior open_app call or an existing navigation history.

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. It reveals the content domain of the log, but says nothing about whether the call is read-only relative to the session, whether log entries are cumulative or consumed, ordering/time-range of entries, 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?

One sentence, front-loaded with what the tool reports, and the colon-list of event types is dense rather than padded. Slightly list-heavy, but every item conveys scope.

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 tool with no output schema, the enumeration of event categories serves as a partial return-value description. It still omits entry format, ordering, volume, and how much history is returned, which an agent would need to interpret results.

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

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

Schema coverage is 100% and the single 'session' parameter is documented as coming from open_app, so the schema does the heavy lifting. The description's phrase 'in this session' reinforces scoping but adds no syntax or format detail beyond the schema — baseline 3 applies.

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

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

The description names a specific resource — the per-session device activity log — and enumerates the event kinds it contains (permission prompts, location reads, scans, fingerprint checks, payments, notifications, shares). That enumeration distinguishes it reasonably from siblings like screen, screenshot, and notifications, though the verb is implied ('what the app did') 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?

There is no when-to-use guidance, no exclusions, and no named alternative. An agent cannot tell from the description whether this overlaps with the sibling 'notifications' tool or when to prefer device_log over screen/screenshot for investigating device activity.

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 does real work by naming the destructive effects: permissions become undetermined, location resets, the camera view is cleared, and the log is wiped. What it omits is whether the session token survives the reset, whether apps must be reopened, and whether in-flight operations are cancelled — material facts for a state-wiping 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?

A single front-loaded sentence with the core action first and the reset facets compressed into a parenthetical — efficient with no filler. The trailing "optionally with a new profile" clause is the one part that costs more ambiguity than it earns.

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

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

This is an unannotated, state-destroying tool with no output schema and two of three parameters undocumented, and the description does not close those gaps. It should say what the call returns (e.g., a fresh session handle), whether the prior session becomes invalid, and what `api` and `platform` control.

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

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

Schema coverage is only 33% (only `session` is documented, as "Session from open_app"), so the description needed to explain `api` and `platform` and does not. Worse, it promises "optionally with a new profile" while no `profile` parameter exists in the schema, leaving the agent unsure which field (if any) carries that intent and creating a mismatch with the actual inputs.

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

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

States a specific verb and resource ("Put the simulated phone back to a known state") and enumerates the exact facets being reset: permissions, location, camera, log. This scope enumeration makes it clearly distinct from siblings like set_device or end_session, which touch only one facet each.

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 "back to a known state" implies when to reach for it (recovering a clean baseline between test runs), and "optionally with a new profile" hints at a variant mode. However, it never states when NOT to use it, nor does it route the agent to alternatives such as end_session (tear down entirely) or set_device (change one setting), 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?

With no annotations, the description carries the full behavioral burden. It discloses that the session is closed and summarizes the report contents, but it omits whether closure is irreversible, what happens to in-flight operations, permission requirements, or error behavior for a likely mutating action.

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

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

The description is a single efficient sentence with the action front-loaded and the return contents following immediately. Every clause contributes useful 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 one-parameter tool with full schema coverage, the description adequately covers the action and the report fields. However, without annotations or an output schema, it should do more to explain session-ending side effects and lifecycle implications.

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, and the schema fully documents it as 'Session from open_app'. The description does not add further meaning beyond the schema, so the high schema coverage supports a baseline score of 3.

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

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

The description uses a specific verb and resource ('Close the session') and adds the resulting report contents. It is clear what the tool does, though it does not explicitly differentiate itself from siblings such as open_app or list_sessions.

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 'Close the session' implies this should be used when ending a session, and the schema notes the session comes from open_app. However, the description itself gives no explicit when-to-use guidance, exclusions, or 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?

With no annotations, the description must carry the safety profile, and it does imply a read-only enumeration by describing the return content ('Apps this server can open, with what each one does'). It says nothing about scope limits, completeness, or whether unopenable/system apps are excluded — gaps that matter for a discovery tool.

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

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

Two short sentences, front-loaded with what the tool returns and followed by the optional filter detail. No filler or redundant 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?

For a one-optional-parameter read tool with no output schema, the essentials are covered: what comes back and how to filter it. Minor omissions are pagination/result-size behavior and match semantics, but nothing blocking for correct invocation.

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

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

Schema description coverage is 0%, so the description is the only source for the single parameter, and it does explain that query matches name, description, or category and gives two concrete example terms. It stops short of stating match semantics (substring vs exact, case sensitivity), which keeps it from a 5.

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

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

States the resource (apps the server can open) and adds that each entry carries a functional description, which distinguishes it clearly from the sibling open_app (which acts on one app). The verb 'list' is implied by 'Apps this server can open' rather than stated directly, which costs it a point versus a crisp verb+resource phrasing.

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 list-then-open relationship with open_app is inferable from the sibling name but never stated, and there is no explicit when-to-use or when-not-to-use. The query examples ('shop', 'douala') do at least show a discovery use case.

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

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

No annotations are provided, so the description carries the burden. It discloses the shape of the returned data (id, app, release, start time) and implies a read-only listing, but doesn't address ordering, pagination, or whether sessions can disappear mid-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?

Two short sentences with the resource and returned fields front-loaded, then the usage cue. 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 and no parameters, the description needs to convey what comes back, and it does list the key fields. A note on ordering or staleness would make it 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is trivially complete. Baseline 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+resource: listing open simulator sessions (phones), and even names the fields returned (id, app, release, start time). It is clearly distinct from siblings like end_session or list_apps, though it doesn't explicitly contrast with them.

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

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

"Use to resume after a reconnect" gives a concrete triggering scenario for calling this tool rather than the alternatives. It doesn't state when not to use it, which keeps it from a 5.

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

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

With no annotations, the description carries the full behavioral burden, and it does add one genuinely useful trait: banners vanish after 5 s, mirroring a real heads-up notification. However, it never states that the tool is read-only, whether reading the shade dismisses or preserves the notifications, or what shape the results take, leaving significant behavioral questions for a stateful device 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 compact sentence with the resource stated first and the notable 5-second expiry detail attached parenthetically. Nothing is wasted, though the sentence is a label rather than an action statement.

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 should clarify what the shade returns (message text? app source? timestamps?) and whether the list is cleared or persisted. The 5 s expiry hint is helpful but the return shape and side effects remain undefined for a one-parameter stateful tool.

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

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

There is a single required parameter, 'session', whose schema description ('Session from open_app') already fully documents it at 100% coverage. The description adds no extra meaning about the session scoping beyond repeating that notifications are per-session, 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 identifies the resource as 'the notification shade' holding notifications delivered to the simulated phone in this session, which implies a read/list of pending notifications. But it uses a noun phrase rather than a verb+resource and never distinguishes itself from the closely related siblings push_notification and open_notification, so an agent must infer which one surfaces vs. creates vs. opens a notification.

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

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

There is no statement of when to call this versus push_notification (which presumably creates one) or open_notification (which presumably taps one), nor any precondition such as requiring an open session. Usage is only implied by the noun phrase.

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. It usefully discloses that a fresh session is created and that the first screen is returned, but it does not explain session lifecycle effects, whether an existing session is replaced, cleanup expectations, or failure/auth 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?

It is a single, front-loaded sentence with no wasted text. The key action and immediate effect are stated efficiently.

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 schema is rich enough to support invocation, and the description states that the tool returns the first screen. However, with no output schema and no annotations, the return format and session side effects remain underspecified for an agent that needs to interpret the result correctly.

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

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

Schema description coverage is 100%, so the schema already documents app identifiers, release syntax, dark mode, session naming, and seed_cart formats. The description adds no parameter-level meaning beyond what the schema provides, making the baseline score of 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?

The description uses a specific verb and resource: 'Open an app', and adds scope/effect with 'in a fresh phone-sized session and return its first screen'. It is clear without opening the schema, but it does not explicitly distinguish itself from siblings such as list_apps or screen.

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 mention of a 'fresh phone-sized session' implies the tool is for starting an isolated app session, but there is no explicit guidance on when to use this versus list_apps, screen, screenshot, or session-management tools. 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?

With no annotations, the description carries the full burden; it does usefully disclose effect semantics ('the app handles it exactly as if its banner was tapped'). However, it omits what happens to the notification afterwards (dismissed from the shade?), whether the shade collapses, and what occurs if the shade is empty.

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

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

A single sentence with the action front-loaded and the default-behavior caveat parenthetically attached; 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-parameter action tool with no annotations and no output schema, the description covers the core behavior and the id default. It is nearly complete, missing only the post-tap state (notification removal, shade state) and error behavior when the shade is empty.

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% (only `session` is documented), and the description compensates for `id` by explaining it is optional and that the newest notification is used when omitted. It still does not say where valid ids come from (presumably the `notifications` tool), which is the remaining gap.

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

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

States a specific verb (tap) and resource (a notification from the shade) plus the default-target rule. It implicitly separates itself from the sibling `notifications` (listing) and `push_notification` (creating), though it never names 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?

The parenthetical 'newest if no id is given' implies when the optional id can be omitted, but there is no explicit guidance on when to use this versus `notifications` or `tap`, and no prerequisites are stated. Usage must be inferred from the verb.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses that changes are audited and that `publish` propagates to every phone within seconds — an irreversible, fleet-wide side effect worth flagging. It says nothing about permissions, failure modes, or whether non-publish commands are local-only.

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

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

A single front-loaded sentence with no filler, and the high-impact `publish` detail is placed where it will be seen. It is efficient, though the brevity is partly why the parameter gaps remain.

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 mutation tool that pushes to live devices, with no output schema and no parameter documentation, the description is thin. It should at minimum point to owner_describe for valid commands and explain what `app` and `args` expect.

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% for three parameters, including a free-form nested `args` object and a free-form `command` string. The description only hints that `publish` is one valid command value; `app` and `args` are never explained, leaving the agent to guess their format.

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 verb and resource ('Run an owner command against the live app'), but 'owner command' is undefined and no example is given. It does not distinguish this from the sibling owner_describe, which presumably enumerates the available commands.

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 reach for this versus owner_describe or the other device tools, and no prerequisite such as discovering valid command names first. The only implied condition is the parenthetical hint that `publish` affects live devices.

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

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

No annotations are provided, so the description carries the full burden. It discloses the auth requirement (PN_OWNER_TOKEN), which is real behavioral value and implies a read-only listing, but says nothing about return shape, ordering, pagination, or what happens when the token is missing or invalid — all important for a discoverability 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?

A single sentence with the resource and scope front-loaded, the enumerated command groups in a cheap parenthetical, and the credential requirement trailing. Nothing is redundant 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?

The tool is simple (one param, no nested objects, no output schema, no annotations), so the description's gaps are limited but real: the "app" identifier format and the relationship to owner_command are unresolved. Given the low complexity, a somewhat terser description is defensible, but these two omissions are the ones an agent will most often trip 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?

Schema description coverage is 0% for the single required "app" parameter, so the description must compensate. "of an app" only faintly ties the parameter to the tool and never clarifies whether it expects an app ID, slug, or display name — a distinction the agent cannot resolve 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?

"List the owner commands of an app" gives a specific verb plus a well-scoped resource, and the parenthetical (content, prices, offers, orders, publish) enumerates exactly what kind of commands are returned. It is clearly distinguishable from generic siblings like list_apps or open_app, though it never explicitly contrasts itself with the sibling named owner_command, which an agent would likely conflate 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?

"Needs PN_OWNER_TOKEN" is a genuine precondition that tells the agent what credential must be present before calling. However there is no explicit when-to-use statement, no mention of whether this is the discovery step that precedes owner_command, and no exclusions — the agent must infer that it should call this before executing an owner command.

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 behavioral burden. It does add genuine value by disclosing the observable effect — a banner renders on the device and is tappable by the agent — which is the key behavioral trait for a simulation tool. It omits whether delivery is synchronous, whether the notification persists in the notification center, and what happens on failure or a stale session.

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

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

One front-loaded sentence with a clear action and a concrete observable result; every clause earns its place and nothing is 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?

A 4-parameter mutation-ish tool with zero annotations, no output schema, a nested free-form object, and 25% schema coverage needs considerably more: session prerequisites, what `data` carries, and expected post-send state. The description covers only the surface effect, leaving the payload contract and failure behavior undocumented.

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 25% — only `session` is described ("Session from open_app"). The description says nothing about `title`, `body`, or the nested free-form `data` object, so an agent gets no guidance on payload conventions or what `data` is for. With low coverage the description was the only place to compensate, and it did not.

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

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

Names a specific verb and resource ("deliver a push notification") plus the target ("the simulated phone"), so intent is unambiguous. However, it never distinguishes this from the sibling `notifications` or `open_notification` tools, leaving the agent to guess which one creates vs. reads vs. opens a notification.

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 scenario (triggering a simulated notification banner the agent can then tap) but gives no explicit conditions, no prerequisites beyond the schema's `session` field, and no statement of when to prefer `notifications`/`open_notification` instead. Usage is inferable from the stated outcome rather than 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?

With no annotations, the description carries the full behavioral burden, and it only discloses that the result is an accessibility tree containing refs. It does not explain what refs are for (presumably targets for tap/type), whether the call is read-only, or how much of the UI tree is included (visible vs. full hierarchy).

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

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

One short sentence fragment, front-loaded with the resource and its format — no waste. It loses a point only because the terseness is achieved partly by omitting necessary detail rather than by tight editing of complete information.

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

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

There is no output schema and no annotations, so the description is the only source of behavioral context, yet it never explains the 'refs' concept that the sibling action tools presumably depend on. For an inspection tool whose output feeds other tools, this leaves a meaningful 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 the single 'session' parameter documented as coming from open_app, so the schema does the work. The description adds no additional semantics about the parameter, which is the expected baseline when coverage is high.

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 resource ('the current screen') and the return format ('accessibility tree with refs'), which is more specific than the bare name 'screen'. However, it is a noun phrase with no verb and never explicitly contrasts itself with the obvious sibling 'screenshot', so the agent must infer that this returns structured UI elements rather than an image.

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

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

There is no guidance on when to call this versus 'screenshot' or the other inspection siblings, and no statement of prerequisites beyond what the schema already says. The agent gets no exclusions or recommended sequencing.

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 disclose the return format as a PNG of the phone screen. However, it does not explicitly confirm that the operation is read-only/non-destructive, nor does it mention capture constraints or whether the session state is affected.

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

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

The description is two short sentences and is front-loaded with what the tool returns. The second sentence efficiently adds the sibling-alternative guidance without redundant restatement.

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 supplies the essential output type and the main usage decision. It could explicitly confirm read-only behavior, but otherwise the agent has enough context 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?

There is one required `session` parameter, and the schema already documents it at 100% coverage as coming from `open_app`. The description adds no parameter-level detail, which is acceptable because the schema baseline carries this dimension.

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

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

The description states that the tool produces a PNG of the phone screen and scopes it to visual checks such as layout, colours, and images. It clearly distinguishes this from the accessibility-tree output of `screen`, though it describes the artifact rather than using an explicit action verb.

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 use case for this tool (checking layout, colours, images) and explicitly routes the agent to `screen` when the tree is sufficient to act. That is clear when-to-use and when-to-prefer-an-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?

No annotations, so the description carries the burden. It does disclose the return ('Returns the new screen'), which is valuable, but says nothing about how far a scroll moves, what happens at page boundaries, or whether the session must already be open (only the schema covers the session param).

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 verb and its two modes, with the return value tacked on last. Nothing is redundant.

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

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

The absence of an output schema is partly compensated by 'Returns the new screen', and the rail/page distinction is covered. However, for a UI-driving tool with no annotations and a required session, missing details on scroll granularity and edge behavior leave a 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 67% and the description adds real meaning the enum alone lacks: down/up are for the page, left/right for a rail, and ref must point at a rail. That maps direction semantics to the ref parameter in a way the schema does not.

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

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

States a specific verb (scroll) plus the two resource scopes: the page vertically and a horizontal rail. It's clearly distinguishable from siblings like tap, screen, or screenshot, though it doesn't 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 parenthetical '(down/up)' vs '(right/left, give the rail's ref)' implicitly tells the agent which direction set applies where, which is useful conditional guidance. There's no explicit when-not-to-use or comparison to alternatives like screenshot/screen for re-checking state.

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. It usefully discloses that this manipulates a simulated phone and that effects apply to the next action, which is real behavioral context. It omits key traits: whether unspecified fields persist or reset, whether repeated calls merge, and whether there are any ordering concerns.

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 a compact enumerated list and a closing timing note. Every clause carries information; 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 7-parameter nested mutation tool with no annotations and no output schema, the description does reasonable work but leaves gaps: it doesn't clarify merge-vs-replace semantics, doesn't explain the required session parameter's role (only the schema does), and says nothing about return behavior or 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 only 14%, so the description must compensate, and it largely does: it maps to six of the seven top-level parameters (location, camera barcode, permissions, biometrics, payment, online). It adds little on nested semantics like camera.delayMs, payment.pin, biometrics.enrolled, or the enum values, but the top-level coverage is strong for a low-coverage 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 opens with a specific verb and resource – 'Change what the simulated phone has' – then enumerates the controllable dimensions (location, barcode, permissions, biometrics, payment, network). An agent can distinguish this from siblings like device_reset or device_log, though the description never names those alternatives explicitly.

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

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

'Takes effect for the next action' is a genuinely useful usage hint about timing. However, there is no guidance on when to use this versus device_reset (which presumably clears such state), no prerequisites, and no indication of what happens to settings you don't specify.

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 burden. It does disclose the key behavioral fact that this is a mutating interaction whose result is the next screen, but it omits whether refs expire after use, what happens on an invalid ref, or whether the tap can trigger destructive app-level actions.

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 redundancy, and the action and its outcome are front-loaded. Nothing could be cut without losing 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 two-parameter tool with no annotations and no output schema, the description covers the essential contract: what it acts on and that the response is the new screen. Remaining gaps (ref lifecycle, error behavior) are moderate rather than fatal.

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

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

Schema coverage is 100%, so both parameters (ref with pattern and example, session sourced from open_app) are already fully documented. The description only echoes the 'by ref' concept without adding format or lifecycle details, 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 (tap) and the target resource (button, link or choice by ref), plus the observable result (returns the new screen). This is clearly distinguishable from siblings like scroll, type and back, though the description doesn't explicitly name those boundaries.

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: tap an interactive element by ref. There is no statement of prerequisites (a live session, a ref from a prior screen call), no failure behavior for stale refs, and no routing to alternatives such as scroll or back when an element isn't visible.

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

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

With no annotations, the description carries the full burden, and it does disclose two important traits: typing overwrites existing content, and the tool returns the new screen. It omits error behavior for invalid/stale refs and any focus or timing preconditions, which matter for an unattended UI-driving tool.

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

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

Two tight sentences with the operation and its overwrite side effect front-loaded, followed by the return value. Nothing is 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?

The tool is simple (4 params, no output schema), and the description covers the return value and the destructive-ish overwrite behavior. Still missing are preconditions (field focus, valid ref) and failure behavior, which an agent needs before driving a UI blindly.

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%: ref, enter, and session are documented in the schema, but text has no description. The description adds meaning for text via "replaces its content" (overwrite rather than append), but does not clarify literal-typing semantics such as newlines or special characters.

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 a text field by ref") and clarifies the effect ("replaces its content"), which separates it from sibling mutators like tap or scroll. It does not explicitly name an alternative tool or contrast with them, so it stops short of a 5.

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

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

Usage is only implied: the "by ref" phrasing hints that the ref comes from a prior screen inspection, but there is no explicit statement of when to use this versus tap/scroll or whether the field must be focused first. No exclusions or prerequisites are given.

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