phone_read_value

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

Beyond readOnlyHint/openWorldHint it discloses real behavioral traits: no focus/wake/lease side effects, refusal on secure fields, refusal on old runners lacking ipu:valueRead instead of promoting a preview, and value withholding on owner/privacy changes. It also warns that 'complete' means only that the AX attribute was not cut by this API, not that the app exposed its full document — a genuinely useful caveat. The only gap is the exact shape of the source/completeness metadata it returns.

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

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

Front-loaded with the core action and its non-effects, then selection rules, then use-case routing, then return/refusal semantics. Dense and largely waste-free, though a few clauses are packed tightly enough to slow parsing on first read.

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

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

Covers purpose, selection preconditions, truncation semantics, refusal paths, and a return-value sketch even without an output schema. Minor gaps remain around accepted 'kind' values and the structure of the returned metadata, but nothing an agent needs to invoke it correctly is missing.

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

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

With 40% schema coverage the description carries extra weight: it defines the identifier-vs-label selection rule, requires freshness of the screen, notes kind is optional, and explains that a smaller max_utf16 yields truncated:true. It leaves 'kind' without any value guidance and never mentions the instance parameter, but the schema documents instance.

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 one current element's AX value') plus a precise non-effect list (no tapping, focusing, waking, owner lease), which separates it from phone_elements and phone_tap_element in the sibling set.

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

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

Gives an explicit trigger ('when phone_elements marks value_truncated or the task needs full field text'), the selection precondition (exactly one identifier or exact label from a fresh screen), and the refusal rule for ambiguity. The alternative is named directly.

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