previewapk_observe

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 stale_snapshot failure mode, the cost/performance tradeoff versus siblings, and that screenshot=true adds image output. It doesn't explicitly state read-only semantics or whether the snapshot is cached, but the read nature is strongly implied by 'Read'.

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?

Information-dense with the core purpose front-loaded in the first clause, and the follow-up workflow and cost tradeoff placed after. The first sentence is a long run-on packed with parenthetical detail, but every clause carries useful signal.

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

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

There is no output schema, so the description must explain the return value – and it does, listing the element fields, reading order, and the compact-text companion form. Combined with the documented failure mode and follow-up usage, an agent has everything needed to call and interpret it.

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

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

Schema coverage is only 33% – `device` has no description anywhere and `screenshot` appears only as a bare boolean with a default. The description rescues `screenshot=true` and clarifies that `scale` applies only when screenshot is true, but the `device` parameter remains completely undocumented in both places.

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 current screen as a compact numbered snapshot') and enumerates exactly what comes back (foreground app, keyboard, elements with ref/type/text/bounds). It also positions itself against siblings by being 'cheaper than a screenshot and cheaper than the full hierarchy', which maps cleanly onto previewapk_screenshot and previewapk_hierarchy.

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 recommends this over a screenshot and over the full hierarchy, and gives a concrete follow-up workflow (keep snapshot_id, pass ref + snapshot_id to previewapk_tap, expect stale_snapshot if the screen changed). It stops short of stating a when-not condition, e.g. when the full hierarchy is actually required.

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