iphone-use

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

Annotations only declare destructive/idempotent/not-read-only; the description adds the crucial mechanics: replacement rather than append, the 16 KiB UTF-8 cap, that empty text wipes notes, that writes persist into future sessions, a no-secrets safety rule, and that errors don't prove delivery so a read-back is required before retrying. This is materially more than the annotations convey.

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

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

Front-loaded with the read/replace split in the first sentence, then the operational details in descending order of importance (destructive semantics, size, clearing, sibling routing, safety, error recovery). Every sentence carries distinct information; 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?

For a destructive, no-output-schema tool, the description covers the write model, capacity limit, clearing behavior, persistence across sessions, safety constraints, retry semantics, and how notes surface in the screen registry block. Nothing an agent needs to call it safely 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 semantics the schema only implies: the size limit in UTF-8, that empty string is a distinct clearing operation versus omission meaning read, and that the bundle maps to an entry found by phone_apps. The instance parameter is left entirely to the schema.

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

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

States a specific verb pair and resource: 'Read or replace persistent notes for one bundle id about app navigation and quirks.' It also scopes the content type (navigation and quirks) and names the sibling it is not (phone_flow_draft), so an agent can distinguish it from the flow-replay 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?

Explicit branches: 'without text, read', 'with text, replace it entirely', 'an empty text clears the notes', plus 'read first to preserve useful notes' and 'Use phone_flow_draft for executable task replay, not these notes.' It also routes bundle resolution to phone_apps, which are all the when/how decisions an agent must make.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: no screen interaction, no owner lease, ordered source fallback with App Store last, exact matches suppressing partials, and the important caveat that installed_verified=false with installation_checked=false means unknown rather than absent. It also discloses the ambiguity-refusal behavior instead of guessing.

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

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

Purpose and safety statement are front-loaded, and the candidate-field/next-step guidance follows logically. It is dense — long semicolon-linked clauses in the final sentence — but nearly every clause carries decision-relevant 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 5-parameter, read-only lookup with no output schema, the description covers what each candidate field means, what the edge-case flags imply, and how to act on results. There is no output schema gap left unaddressed and no missing prerequisite.

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 query/limit/source/country/instance are already documented at the parameter level. The description reinforces `source` ordering semantics and the name-vs-bundle-id form of `query`, but adds little about limit, country, or instance. Baseline 3 is right when the schema carries the detail.

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

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

Opens with a specific verb+resource+goal: "Find an app's bundle id by name instead of guessing it." That immediately separates it from phone_install_app (which installs) and from launch tools, so an agent can pick it without reading schemas.

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 exact search cascade (phone list -> bundled catalog -> App Store) and what selects each stage via `source`. It also names the follow-on alternatives explicitly: pass a bundle id to launch_app, or hand launch_app the exact name and let the daemon refuse ambiguity rather than guess.

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

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

Goes well beyond the readOnlyHint annotation: it discloses 'no device connection, wake or owner lease', that 'supported is static' while 'available is cached', the full blocked_by vocabulary, and critically warns 'ok:null is unknown, never proof of readiness'. This is exactly the kind of subtle behavioral context annotations cannot convey.

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

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

Purpose is front-loaded and most sentences carry distinct, non-redundant facts. It is quite dense and packs several caveats into a short span, but nearly every clause (vocabularies, blocked_by values, ok:null warning) 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, but the description explains the return semantics fully: supported vs available, blocked_by enumeration, and the ok:null ambiguity. Combined with the read-only annotation and complete parameter schema, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100% and the single 'instance' parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no further meaning to the instance parameter, but it doesn't need to since the schema is complete.

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 ('Inspect supported UI operations and cached readiness') and explicitly differentiates from the sibling phone_status ('Unlike phone_status (device/setup/owner diagnostics), this names the backend's single-step, batch and perform vocabularies'). An agent can distinguish the tool from its siblings without opening the schema.

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

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

Gives explicit when-to-use ('before choosing an action') and a named alternative with condition ('If blocked, follow phone_status guidance instead of probing with actions'). Also delimits scope ('This describes UI control only, not app installation or other device management'), routing installation work away.

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

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

Annotations only say readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false; the description adds far more: stop conditions (duplicate_page, end_label, max_pages), why duplicate_page is not proof of the end, that only accessibility-tree-exposed content is collected, that the screen is left on the last page, that a snapshot mismatch refuses before swiping, that owner/privacy changes halt reads, and that uncertain swipes must never be replayed. This is consistent with readOnlyHint=false since it swipes the live device.

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

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

Core purpose is front-loaded in the first clause and nearly every sentence carries operational signal. It is dense to the point of a run-on and repeats the duplicate_page idea ('stops when the exposed page repeats' then 'duplicate_page is not proof the list ended'), which costs some tightness.

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

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

With no output schema, the description carries the burden of explaining returns and does so: rows and deduplication, `complete`, `business_complete`, `duplicate_page`, `snapshot`, `swipes_confirmed` vs `swipes_uncertain`, and that results name the app. For a 7-parameter, state-changing tool, an agent has enough to call it correctly and interpret the response.

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; the description earns above that by adding semantics the schema lacks — the dedup key (kind, identifier, label, value), that end_label alone drives complete:true, that max_pages caps at 10, and that snapshot is never auto-filled. It does repeat some schema-stated defaults (default Cell, default 6).

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 a scrolling list across pages in one call, reading rows of one kind, swiping, re-reading — and explicitly contrasts it with the 'scroll + read turns' pattern a sibling like phone_scroll would require. An agent can tell what it does without opening the schema.

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

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

Says when to prefer it (batch list collection instead of alternating scroll and read turns) and gives a prerequisite, 'Requires phone_status drivable=true'. It does not explicitly name the alternatives (phone_scroll, phone_scroll_find) or state when not to use it, so routing between list tools is still partly inferred.

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?

readOnlyHint=true already declares the safety profile, and openWorldHint is present, so the bar is lower; the description still adds the notable fact that the tool never touches the screen, which matters among screen-manipulating siblings. It also discloses the returned fields for each mode (name/process/time/size vs exception/crashed thread/backtrace), useful context given there is no output schema.

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 dense sentence pair, front-loaded with the resource and the mode switch, with no redundant restatement of the tool name. Every clause carries either mode selection or return-contract information.

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

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

With no output schema, the description carries the return-value burden and does so for both modes. The only omissions are the default page size and the `instance` targeting behavior, both of which are covered by the schema, so nothing an agent needs to call 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 a 3 is the floor, but the description goes further by explaining the coupling between `name` and the result shape (a report name switches the tool from list to detail mode) and that `process` is a list-only substring filter. It does not mention `limit` or `instance`, which the schema handles adequately.

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

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

States a specific resource (crash reports) and both verbs it implements: list without `name`, read a single report with `name`. The dual-mode split is spelled out so the agent can predict the output shape before calling, and the closing clause separates it from the screen-driving 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?

The when-to-use logic is explicit for both modes: omit `name` to enumerate, supply a `name` taken from the list to read detail, and use `process` to narrow the list. What's missing is any pointer to an alternative tool for related diagnostics (e.g. logs), so an agent comparing siblings gets context but no explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds substantial context beyond that: snapshot tokens are valid for this read only, 200-row / 32 KiB text budgets, omission notices mean partial views not absence, hidden rows must be scrolled into view before acting, and alert blocks block taps. That is genuinely useful behavioral context, though the return format is described in dense, hard-to-parse prose rather than structured disclosure; a 3 reflects solid added value over the annotation baseline without being exemplary.

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

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

Front-loading is excellent — the cheapest-vs-screenshot claim and the sibling reference come first — but the remainder is a single dense paragraph mixing return shape, filter semantics, budgeting, alerts, registry, OCR and the value_truncated handoff. Multi-topic content this important (alerts block taps, hidden rows need scrolling) is buried mid-paragraph where an agent scanning for call conditions can miss it.

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 6-parameter read tool with no output schema, the description covers return row fields, size/row budgets, truncation semantics, hidden-row behavior, alert handling, registry discovery, and OCR fallbacks — everything needed to call and interpret it. 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 100%, so the baseline is 3, but the description adds real semantic layering: it explains the evaluation order (selector.index applies after scope/query and before limit) and that the ordinal retains the original snapshot row index, plus that ordinal matching refuses when earlier candidates are unknown or scope is incomplete. It also clarifies that value_present covers empty/truncated strings and that SecureTextField rows match neither boolean.

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?

Opens with a concrete verb+resource: 'The current screen as text', and immediately distinguishes itself from phone_screenshot ('use this instead of screenshots'). It also names the exact return shape (kind, label, identifier, value, rect, state, snapshot), so an agent knows precisely what it gets without opening a schema.

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

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

Explicit routing to alternatives: phone_tap_element consumes the snapshot token, phone_read_value for full bounded values, phone_flow_run when the registry block shows a saved flow, phone_tap with x/y for OCR rows. It also states preconditions ('Requires phone_status drivable=true') and when to narrow ('Narrow with query when needed').

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

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

Annotations already mark this as a non-read-only, non-destructive, non-idempotent write, and the description adds substantial context beyond them: what is recorded (single actions and phone_run_steps batches, not flow runs), what is deliberately excluded (typed text never included), and the file-write safety property (save_as never overwrites existing files, validated after write). This is rich disclosure an agent could not infer from structured fields.

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

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

Dense but front-loaded, with the core action stated first and the workflow and caveats following. The parenthetical aside is slightly run-on, but every sentence carries actionable information; minor tightening would make it a 5.

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

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

No output schema exists, and the description fills that gap by explaining the return value (a flow v1 document with locator/input mapping plus a `todo` list). Combined with prerequisites and the follow-on workflow, an agent has everything needed to call and use it correctly.

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

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

Schema coverage is 100%, so the schema already documents both params, making baseline 3 appropriate. The description goes further by explaining the save_as lifecycle (write to new file, validate, then fix/run/publish), adding meaning beyond the schema, though it does not discuss the `instance` parameter.

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

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

States a specific verb and resource ('turn what you just did on the phone into a flow') and clarifies the mechanism (daemon action trail, not flow runs). It clearly distinguishes this drafting tool from siblings like phone_flow_run, phone_flow_list, and phone_flow_publish.

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 triggers ('when a response carried flow_suggestion, or after any multi-step task with no matching flow'), an exclusion, and a mandatory prerequisite ('ASK THE USER before saving'). It also names the follow-on workflow (fix todo, phone_flow_run, publish with user OK), routing the agent precisely.

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?

Beyond the readOnlyHint annotation, the description discloses that invalid or missing ids return an error 'without running or downloading anything', that placeholders are shown but runtime values are not, and that the caller should verify app, locale, verification and side effects before execution. That is meaningful behavioral context an agent cannot get from annotations alone.

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

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

Front-loaded with the core purpose and return contents, then the id constraint, then failure behavior and siblings. It is dense with multiple clauses per sentence, but virtually every clause carries actionable information, so little 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?

Covers the gap left by the absent output schema by describing what is returned (metadata, declared inputs, step templates with placeholders) and what is not. Format constraints, error behavior, and workflow position are all present, so an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds real value beyond the schema by specifying the id format ('exactly two lowercase app/flow slugs, not a local file path') and giving a concrete example, though it says nothing extra about the instance parameter.

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

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

States a specific verb and resource ('Inspect an installed flow') and immediately enumerates what it returns ('metadata, declared inputs and step templates') plus what it explicitly does not return ('never runtime input values'). It is clearly distinguished from siblings phone_flow_run (which executes), phone_flow_list (which enumerates), and phone_flow_update (which populates the registry).

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

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

Explicitly prescribes the precondition ('Use an id from phone_flow_list'), names alternatives with their conditions ('use phone_flow_update if the registry store is empty', 'validate its file instead of guessing a registry id' for local drafts). It also states the purpose in the workflow ('before phone_flow_run').

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that filters AND-combine, that app takes a registry directory or bundle id and is explicitly NOT a display-name search, what the compact row contains, what detail=true changes, and the important caveat that 'verified' means a recorded hardware run rather than a per-version guarantee. That is exactly the kind of semantic and trust caveat structured fields cannot carry.

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

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

Front-loaded with purpose then alternative then caveats, and every clause is substantive rather than filler. It is dense to the point of being a run-on in places, but trimming any sentence would lose 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?

No output schema exists, and the description compensates by describing the compact row fields (id, description, inputs, risk, compatibility) and what detail=true returns. Combined with the empty-store and verification caveats, an agent has enough to call this 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 the baseline is 3; the description earns a bump by adding filter-combination semantics and the app-parameter disambiguation ('registry app directory or bundle id, not a display-name search') that the schema text does not state. It does not add much on `instance` or `detail` beyond what the schema already documents.

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 ('Find installed') and resource ('deterministic per-app flows') with scope ('before exploring a task') and immediately distinguishes itself from phone_flow_run by noting a match can replay without model decisions. An agent can tell this apart from phone_flow_info, phone_flow_run and phone_flow_update without opening any schema.

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

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

Explicitly positions the tool in a workflow ('before exploring a task'), names the alternative for deeper inspection ('Use phone_flow_info to inspect effects before running'), and gives the remediation path for the empty case ('An empty store needs phone_flow_update once'). It even forecloses a false conclusion ('a filter with no matches is not proof that the whole store is empty').

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotence, so the safety bar is partly covered. The description adds valuable context beyond that: it forks if needed, writes app.json, rebuilds index.json, pushes a branch, opens a public PR, opens a draft PR for unverified flows, and advises inspecting pr_url before retrying. This is exactly the extra behavioral detail an agent needs.

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

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

The description is front-loaded with the core action and packs a lot of useful detail into one paragraph. It is dense but every sentence mostly earns its place; minor deductions for being a single run-on paragraph and for the wasted mention of verified_on.

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

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

For a complex, non-idempotent mutation tool with no output schema, the description covers the return fields (id, repo, branch, head, pr_url), the confirmation gate, and retry guidance. It is nearly complete, but the phantom verified_on parameter and thin coverage of instance/app_name/note leave small gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a little meaning for source ('local file or installed flow id') and aliases ('foreground-app labels by language'), but it also references a 'verified_on' field that is not present in the schema (which has additionalProperties=false), creating a potential misdirection for the agent.

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 ('Publish a working flow to the official registry') plus the mechanism ('through the user's GitHub CLI login'). It clearly distinguishes itself from sibling tools like phone_flow_draft, phone_flow_run, and phone_flow_report by naming them as prerequisites or 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?

Gives explicit sequencing: create a draft with phone_flow_draft, prove it with phone_flow_run, and use phone_flow_report for existing problems. It also gives a clear gating condition for confirm=true ('only after the user agrees to that publication'), leaving little ambiguity about when to call 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?

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds material context the annotations cannot: the target is a public, outward-facing registry, an explicit user-consent gate is required, and the submitted payload has screen labels, typed text, and element lists stripped. Not stated is duplicate-issue handling or whether the call is rate-limited, so this falls just short of fully complete.

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

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

Purpose comes first, then the implicit data source, then the privacy guarantee, then the consent gate, then the exclusions — a deliberate ordering with no filler. Every clause (including the failure-type parenthetical) carries decision-relevant 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 4-parameter, single-object tool with no output schema and annotations already covering the risk profile, the description supplies the remaining decision inputs: precondition of a prior run, consent requirement, redaction scope, and negative cases. An agent can determine whether to call it and how to prepare the note without further information.

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

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

Schema coverage is 100%, so baseline is 3; the description earns an extra point by explaining that the id scopes the report to the last phone_flow_run of that flow (so the failure data is implicit) and that this means the caller 'only add[s] a short note'. The confirm semantics are reinforced as a consent gate rather than a technical flag.

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 — 'File an issue on the official flow registry' — for 'an installed flow that failed', and the parenthetical enumerates the failure classes (label changed, app updated, wrong locale). This is clearly distinct from siblings like phone_flow_publish, phone_flow_draft, and phone_flow_run without needing their schemas.

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 the positive precondition (a failure captured by the last phone_flow_run of that id), the gating requirement (confirm=true only after the user agreed), and explicit exclusions (do not file for a locked/offline phone, or for a flow run on the wrong app/locale). Both when-to and when-not are stated, plus the alternative interpretation of the failure.

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

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

Annotations declare a destructive, non-idempotent, open-world write, and the description goes well beyond them: one control lock is held, the daemon validates the whole sequence and stops at the first failed step, retry_safe=false forbids replay, and read_only flows auto-run their other-language variant with fallback_from reported. None of this contradicts the annotations and much of it cannot be inferred from them.

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

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

Front-loaded with the core action and scope, and every sentence carries operational information (return shape, locking, fallback, refusal gates). It is dense as a single unbroken paragraph, which makes the retry_safe=false warning easy to miss, but there is little waste.

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

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

There is no output schema, and the description compensates by explaining what comes back: top-level outputs, completed/applied counts, the failed step, verify.ok drift reporting, and fallback_from. For a 7-parameter destructive tool with nested inputs, an agent has everything needed to call it and to 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 per-field meaning is already documented and baseline is 3. The description adds cross-parameter semantics the schema does not: inputs are the flow's declared inputs used for one run only, confirm is gated on prior user confirmation, and force is tied to compat state — a modest but real value add.

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 ('Run one flow exactly once') and immediately broadens the id semantics to registry id or *.json draft path, which separates it from phone_run_steps, phone_run_start and phone_flow_publish. It also names the sibling tools an agent would otherwise confuse with it (phone_flow_draft, phone_flow_list, phone_elements).

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 preconditions ('Requires phone_status drivable=true'), refusal conditions (risk=side_effect needs confirm, broken/incompatible compat needs force), and an alternative action on failure ('inspect phone_elements, repair the flow, do not guess'). It also states that unverified flows may need a checkpoint screenshot, which routes the agent to the next tool.

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

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

Annotations already declare idempotent, non-destructive, open-world behavior; the description adds the concrete reason ('locally added flows are kept') plus checksum verification and strict pre-write validation, so an agent knows local edits survive. It does not say what happens to partially failed syncs or whether network errors are reported as a 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?

Three sentences with zero padding: what it does, its safety properties, then the call condition. The scope statement is front-loaded and the guidance is last, which is the natural reading 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?

Covers the essentials of a network-fetching, store-mutating tool with no output schema: what is written, how it is validated, what is preserved, and that the phone itself is untouched. Missing only failure-mode detail (what an agent sees on a partial or checksum-failed sync).

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 optional 'instance' parameter is documented there with its fallback behavior, so the description adds no parameter meaning. Baseline 3 applies when the schema carries the full burden.

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: mirror the official iphone-use flow registry into the local store. It is clearly distinguishable from phone_flow_list (read), phone_flow_draft (authoring) and phone_flow_publish (pushing out) named among the 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?

Gives an explicit trigger ('Call once when phone_flow_list reports an empty store, or to pick up new flows'), tying usage to a named sibling's output. It also bounds the call ('call once'), which prevents a polling loop.

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

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

Goes well beyond the annotations: it discloses watchdog semantics, the 0-clears and max-14400 bounds, the private-mode consequence (screen not read or streamed, and that extending without private lifts privacy), and two named failure modes (device_release_in_progress, phone_owned). Annotations only cover the safety profile (readOnlyHint=false, idempotentHint=true), so this added context is substantial.

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

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

Front-loads the core action and bounds, then packs guidance, privacy rules, and error conditions in that order. It is dense but every clause carries operational meaning; the single long paragraph and parenthetical asides make it slightly harder to scan than a bulleted form would.

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 mutating, timer-based lease tool with no output schema, the description covers purpose, bounds, privacy implications, cleanup, and failure modes. An agent has everything needed to invoke it correctly and avoid the common misuse of leaving a stale hold.

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; the description earns more by tying `private` to a real situation ('when the person signs in') and warning that it must be re-passed on extension or the privacy lapses — a non-obvious coupling the schema only partly conveys. It does not clarify the `instance` fallback behavior, which the schema already documents.

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: 'Keep the phone for a bounded human-in-the-loop pause inside the current user-requested task,' and gives concrete examples of what the operator does (types a PIN, approves a prompt, fetches a code). It also carves out the scope against sibling behaviors ('Not for initialization, health checks, or keeping the phone ready'), so an agent can distinguish it from phone_status or phone_capabilities.

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

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

Explicit when-to-use (a human step in the current task), explicit when-not ('Not for initialization, health checks, or keeping the phone ready'), and an explicit termination rule ('clear it when the step is done'). The guidance is actionable without opening any schema.

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

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

Goes well beyond the annotations: apply/restore replace the whole layout, the replaced layout is backed up first, and SpringBoard may reintroduce App Library apps across several passes so a re-read is required after writing. Also discloses that an unreadable device errors rather than returning an empty screen. The read/write split is consistent with readOnlyHint=false and destructiveHint=true; a 5 is withheld only because eventual-consistency timing and partial-failure reporting on apply are not pinned down.

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 correctly with the read purpose and page-index caveat, but it is a single dense paragraph that folds the read contract, coordinate semantics, device prerequisites, and four write actions into one block with no separation between read and write modes. Every sentence carries information, yet the structure forces re-parsing to find the write rules.

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 five-parameter tool with no output schema and a destructive write path, the description covers prerequisites (usbmuxd, no Runner needed), failure behavior (error not empty result), output-field semantics (positions_complete, null positions), write ordering and confirmation, and undo. An agent has enough to invoke both the read and the write modes correctly without guessing.

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?

Adds meaning the schema cannot: page indexes are persisted icon state including hidden and Focus-filtered pages, not the visible page-control indexes, and row/col values are derived from icon-state order and grid metrics with null or positions_complete=false meaning unknown rather than safe. Also clarifies file is a plist on the Mac produced by a backup and that confirm is a human-agreement gate, so the write contract is unambiguous.

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?

Opens with a specific verb and resource set: 'Read all home-screen pages, Dock, folder pages and widget stacks from the paired iPhone', and explicitly separates itself from screenshot/tap siblings ('without opening folders, swiping, or taking screenshots'). The tool is really two modes (read plus backup/preview/apply/restore) bundled under one name, so an agent must read the whole paragraph to learn the tool also mutates, which keeps it 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?

Gives explicit when-to-use and when-not-to-use conditions: no drivable=true or XCTest Runner needed, and 'never reconnect or open Home solely for this read'. For the write path it names the required sequence (backup or preview first, then apply/restore only with confirm=true after the person agreed to the preview) and the recovery path ('Undo with action=restore'). Alternatives are named rather than 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?

Goes well beyond the annotations: it discloses that fresh=true uninstalls first and destroys app data, that blocked apps are refused, that the call can take minutes, and what is returned (the installed bundle id). That is exactly the extra context an agent needs for a destructive, slow, non-idempotent operation.

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 but front-loaded paragraph: the core action and accepted sources come first, then behavior, then the safety caveat. No filler sentences and nothing redundant with the schema.

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

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

For a no-output-schema, four-parameter mutation tool this covers duration, failure mode (blocked apps), data loss, and return value. It omits any mention of the `instance` selector, which is the only remaining 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 already 100%, but the description adds meaning by presenting path and url as mutually exclusive source choices and by spelling out the side effect of fresh (data deletion). The `instance` parameter is left to the schema, keeping it just short of 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 a specific verb and resource ("Install an app build on the phone") and enumerates the two source forms (local path vs https url), so an agent immediately understands the operation and its inputs. No sibling tool overlaps with installing apps, and the description makes that distinction obvious without opening the schema.

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

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

Gives a real usage constraint ("Install only what the user asked for") plus the conditional rule for fresh=true and the refusal of operator-blocked apps. It stops short of naming alternatives or when-not-to-install scenarios more broadly, but the context needed to pick and use this tool is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's real contribution is the no-side-effect boundary ('does not start, reconnect or claim') and the non-fallback rule for missing/invalid instances, which prevents a dangerous silent substitution. It stops short of describing the inventory's shape or what read-only status values look 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?

Front-loaded with purpose and negative scope, and most sentences carry operational weight. It is dense and slightly instruction-heavy for a zero-argument listing tool, but nothing 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 no-parameter, no-output-schema read tool, the description covers what is listed, what it is not, failure remediation, side-effect boundaries, and how its results feed into sibling calls. An agent has everything needed to call it and 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?

The tool takes zero parameters, so the baseline is 4 and the schema needs no elaboration. The description's discussion of 'instance' concerns sibling phone_* calls rather than this tool's own inputs, which is useful context but not parameter documentation for this call.

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 ('List installed local iPhone instances') plus the key attribute returned ('read-only status'), then immediately distinguishes this inventory from paired/connected devices so it can't be confused with device-discovery siblings like phone_status or phone_reconnect.

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 sets boundaries ('Does not start, reconnect or claim a phone'), gives a remediation path for recovery_owner=unconfigured (xcrun devicectl list devices, iphone-use doctor on the daemon host), and tells the agent to ask which phone when ambiguous. It also explains the downstream convention of passing instance to any phone_* call.

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

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

Goes well beyond the annotations by naming the terminal states (done / blocked / max_steps), returning step history, the ~1–2 s per-step cost profile, and the safety behavior of answering BLOCKED rather than sending, paying, deleting or sharing unrequested actions. That last point is the real value-add given destructiveHint=true and openWorldHint=true. Missing only finer detail such as what happens on a mid-run crash or how step history is shaped, which keeps it at 4 rather than 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?

Front-loaded with the core distinction and the alternative check, then cost, then outputs, then safety, then credentials — a sensible priority order with no filler sentences. It is dense with parentheticals (key paths, timing) and runs long for a single prose block, costing it a point on readability.

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

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

There is no output schema, and the description compensates by declaring the terminal statuses and that step history comes back. For an autonomous, non-idempotent, destructive-capable agent tool it also covers credentials (TYPESAFE_API_KEY, TEXT_MODEL_API_KEY with file fallbacks) and verification expectations, leaving no obvious gap for an agent to call it correctly.

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

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

Schema coverage is 100% and each parameter already carries a substantive description (app bundle id, instance with no fallback, max_steps default 30), so the schema does the heavy lifting. The description reinforces the goal contract ('with every value it needs', never invents personal data) and clarifies max_steps via the 'stops with ... max_steps' phrasing, but adds no format or syntax detail beyond the schema — baseline 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?

States a concrete verb and resource ('hand ONE whole goal to a fast on-phone agent') and immediately contrasts it with step-by-step driving, which is exactly the axis on which it differs from siblings like phone_run_steps and phone_tap_element. The mechanism (Jev picks the next operation from the screen's element table, a small LLM types values) makes the tool's role unmistakable.

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

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

Explicit when-to-use ('a clear multi-step goal with no saved flow'), an explicit prerequisite check ('check phone_flow_list first'), and explicit user-facing caveats ('confirm such goals with the user first', 'Verify the end screen yourself'). It routes the agent away from this tool when a saved flow exists and tells it what to do after the call.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, yet the description still adds real context: unsupported names fail before any input is sent, observe defaults on and returns the settled screen, and repeating a key can submit or erase content twice. It stops just short of describing per-key effects in detail.

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

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

Four sentences, no filler. The core action is front-loaded, followed by alternatives, then hazards, then the failure/observe behavior — each sentence carries distinct operational value.

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

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

For a destructive, non-idempotent input tool with no output schema, the description covers preconditions, side effects, return behavior ('the settled screen change'), and recovery on ambiguous results. Nothing an agent needs to invoke it safely 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; the description earns an extra point by explaining what 'observe' returns and by adding validation behavior for 'name' (unsupported names fail before input is sent) beyond the schema's accepted-name list.

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 a navigation or editing key') plus scope ('in the foreground app, acting on its current focus'). It actively distinguishes itself from siblings by naming phone_type and phone_tap_element and stating what each is for.

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

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

Explicit routing: use phone_type for literal text, phone_tap_element to focus a field first, and check phone_status.drivable prior to acting. It also gives a when-not rule for retries ('on an unknown outcome, inspect the screen before another key').

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

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

Adds substantial context beyond the annotations: no password or username traverses the conversation, the entry is matched to the app, ambiguity requires user input, at most two code requests per login, push approval must be handled by the user, and the screen should be read afterwards to confirm. That is real behavioral disclosure for a destructive, open-world mutation.

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

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

Front-loads the core action and credential-safety point, then layers the exclusions and code flow. Dense but every sentence carries operational content; slightly long for a single paragraph.

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

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

No output schema exists, so the description compensates by describing the answer shapes the agent must react to (a list of matching entry names, needs_code) and the required follow-up of reading the screen. An agent has enough to call it and handle the common branches without guessing.

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 when-and-why for `item` and `user` (disambiguation after a name list is returned), when to pass code_via/code_from (only in the needs_code case), and the retry limit. It does not re-explain submit or instance, which the schema already covers.

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: logs an app on screen in using the user's own vault entry, with the daemon doing the typing. This is clearly distinct from siblings like phone_type or phone_tap, which it does not overlap 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?

Explicit trigger ('when an app shows its login page during a task the user asked for'), explicit exclusions ('never sign-up, password changes or payment'), and a fallback path when several entries match (ask the user, then pass item/user). The verification-code path and the two-request cap are also 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?

Beyond the annotations, the description discloses important operational behavior: a reachable paired device is required, connection or auth failures are errors rather than empty logs, capture self-stops after 15 minutes without reads, and clear discards the in-memory buffer. It also documents the output line format, including that error output contains faults, and warns that logs may contain private app data.

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 dense but front-loads the core purpose and the key sibling alternative. Subsequent clauses cover the action lifecycle, failure behavior, timeout, cursor workflow, output format, and privacy warning without obvious 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 multi-action tool with seven optional parameters and no output schema, the definition supplies the missing operational context: action lifecycle, default behavior, timeout, error semantics, cursor usage, output line format, and privacy considerations. Combined with the annotations, it is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is already 100%, so the parameter-level documentation is strong without the description. The description still adds cross-parameter meaning by clarifying that filters apply to read results and that the previous read's next cursor should be supplied as since for incremental reads.

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: capture and read the paired phone's live system log for app debugging. It also explicitly distinguishes this tool from the sibling phone_crashes for saved crash reports, so an agent can route correctly 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?

It gives a clear workflow: start capture, reproduce the issue, then read as the default; stop releases the relay and clear discards the buffer. It names the alternative phone_crashes and the condition that should select it, and explains that filters apply only to read results and that the returned cursor should be passed as since for incremental reads.

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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses that no phone connection, Runner launch, or control lease is acquired, that a shared 12 KiB row budget may silently reduce results with truncation explicitly flagged, and that some fields are intentionally null. These are exactly the operational traits an agent cannot infer from annotations.

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

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

Front-loads the core purpose in the first sentence and groups caveats afterward; nearly every clause carries distinct information (limits, null semantics, no-reconnect rule, excluded counters). It is dense but slightly overloaded with hedging clauses in a single paragraph.

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 does the necessary work of enumerating what the aggregate contains and how truncation appears in the response. It does not describe the shape of the returned rows (per-run vs. per-section fields), leaving a small gap for a reporting 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?

Schema coverage is 100%, so both parameters are already documented, including the limit default of 5, maximum 20, and the shared 12 KiB budget note. The description's mention of 'Default latest 5 open and recent runs, maximum 20' and 'selected instance' largely restates the schema rather than adding new syntax or constraints, so baseline 3 applies.

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

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

States a specific verb and resource ('Read task performance aggregates') scoped to the caller's X-Phone-Owner and a selected instance, then enumerates the exact contents (HTTP-call counts, batch/flow usage, stale/unknown outcomes, losses, p50/p95 latency). An agent can tell this apart from phone_logs or phone_status without opening the schema, though no sibling is named directly.

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

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

Provides explicit exclusions and boundaries: 'Never reconnect solely for metrics' steers away from phone_reconnect, and 'Global cross-owner loss counters are excluded' plus 'model_round_trips remains null without a complete declared trace' clarify when the data will be absent. It gives clear context but does not name a positive alternative tool for adjacent needs (e.g., raw logs).

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?

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.

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

Annotations only say readOnly=false, idempotent=false, openWorld=true, destructive=false; the description adds substantial context beyond that — the phone is occupied, an operator may need to unlock it, idle release is intentional, reconnecting has observable setup_phase/setup_message, and an externally managed runner yields an operator-owned recovery error. It stops just short of describing failure messages in full, but the coverage is well above the annotation bar.

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

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

Front-loaded with purpose, then preconditions, then the call-once-and-wait protocol, so an agent can act on the first sentences. It is dense and slightly repetitive ('Idle release is intentional' plus the repeated blocker/releasing prohibitions), but nearly every clause encodes a distinct rule.

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 naming wait.outcome states and the blocking conditions under which the call returns. For a state-mutating, operator-dependent tool, setup/recovery/error behavior is all covered.

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; the description still adds value by recommending wait_secs=180 with a rationale (runner rebuild after upgrade takes 1–2 min), and by naming the wait.outcome values (drivable, blocked, stopped, timeout) that the schema does not enumerate. The instance parameter is left entirely to the schema.

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

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

States a specific verb and resource — 'Start/restart on-device automation for the configured phone' — and immediately bounds scope with 'This tool never accepts a UDID and cannot switch devices,' which separates it from device-selection or multi-device siblings like phone_instances.

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 when NOT to use it (initialization, status/health checks, completed task, keeping the phone ready) and names the alternative implicitly (phone_status for status). It also gives hard preconditions: phone_status must be released/offline, recovery_owner=daemon, inspect hint/setup_blocked_on first, and no reconnect while releasing or blocked.

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

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

Adds substantial behavior beyond the annotations: auto-stop at 10 minutes or 200 MB, 'ended' explains why a run stopped, the daemon-side storage location under runs/recordings, the required device stream and writable output, and an explicit privacy/security caution about screen contents and the returned Mac path. Nothing here merely restates readOnlyHint/openWorldHint.

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

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

Purpose and lifecycle are front-loaded in the first clause, with differentiation and safety notes after. It is dense and packs several clauses into one paragraph, but almost every clause carries operational value; only the privacy admonition is marginally longer than needed.

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

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

With no output schema, the description still covers what the agent gets back (path, duration, size, 'ended' reason), the failure prerequisites, the size/time caps, and where files land. That is everything needed to invoke and interpret the 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?

Schema coverage is 100%, with action values ('start', 'stop', 'status') already documented in the schema and the instance fallback behavior described there. The description adds no additional syntax or format detail for either 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 specific verb and resource ('Record the iPhone screen to an MP4') plus the lifecycle (start / task / stop), and explicitly contrasts itself with phone_screenshot (one image) and phone_screen (live panel). An agent can pick this over its siblings without reading any schema.

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

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

Gives the operating sequence (start, perform task, stop to get path/duration/size), says when to use 'status' instead ('checks the recording without starting one'), and names the alternatives plus the condition that distinguishes them. Prerequisites (usable video stream, writable output dir) are also 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?

Goes well beyond the annotations by disclosing the success shape (ok with owner=null), that releasing an already-unowned phone succeeds, the exact failure mode for another session's lease (phone_owned, never taken over), and that auth/transport failures surface as errors. It even recommends a verification step via phone_status.owner. This is fully consistent with readOnlyHint=false and idempotentHint=true and adds real context on top.

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

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

Four tight sentences, front-loaded with the primary action and its effect, then the disambiguation, then outcomes and error semantics. No filler or redundancy; 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?

With no output schema, the description carries return-value duty and does so (ok/owner=null vs phone_owned), plus error behavior and a verification hint. For a single optional-parameter mutation tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single optional 'instance' parameter is fully documented in the schema, so the description need not repeat it. The description adds no parameter meaning of its own, 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 (release) plus resource (this session's phone lease) and the triggering condition (when its task ends). It explicitly positions itself against the sibling phone_hold(secs=0), so an agent can distinguish the two without reading 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?

Names the alternative (phone_hold with secs=0) and explains exactly how they differ in effect: giving up ownership versus clearing a pause. It also implies when release is appropriate (task ends, wanting another session to drive immediately).

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

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

Annotations already define the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds important behavioral context beyond annotations: closing is accounting-only, does not stop video recording or release the owner lease, and an already-closed run produces no new summary. It could say more about failure modes or return shape, but it meaningfully exceeds the annotation baseline.

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 return metrics, then adds usage constraints and sibling alternatives. It is dense but every sentence carries useful information; minor wording complexity in the metrics list keeps it from being maximally crisp.

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 non-idempotent close/accounting tool with no output schema, the description is complete enough: it names the metrics returned, explains the required run/session linkage, covers the special turn_ids condition, and clarifies what the tool does not do relative to phone_record and phone_release_owner.

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%, with run_id undocumented in the schema. The description compensates by explaining that the same run_id and session must be used, and it clarifies turn_ids semantics: supply them only for a complete_trace declaration, include every model generation, and otherwise model_round_trips remains unknown. The instance parameter is left to the schema, which is acceptable.

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: close a live task opened with phone_run_start and return its metrics. It distinguishes the tool from siblings by naming phone_run_start, phone_record(stop), and phone_release_owner.

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

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

It gives explicit when-to-use and when-not-to-use guidance: use the same run_id and session, a missing or already-closed run cannot produce a summary, supply turn_ids only for a complete_trace declaration, and use phone_record(stop) and phone_release_owner for recording and lease termination.

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

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

The annotations already declare this is not read-only, not idempotent, not destructive, and not open-world; the description adds substantial context beyond that. It clarifies that the tool does not drive or reserve the phone, how later calls count toward the run, what happens when reusing an open run_id, and what complete_trace commits the caller to.

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 its core purpose, then packs only relevant operational details into a compact paragraph. Each clause adds distinct value: alternative routing, optionality, run_id reuse, complete_trace timing, and error-reporting behavior.

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

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

Given there is no output schema, the description correctly states what is returned: a start acknowledgement and the need to report errors rather than assume metrics were recorded. It also covers the tool's operational role, optionality, and key constraints, making the definition complete 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 coverage is 100%, so parameter documentation already carries much of the burden. The description still adds meaning beyond the schema by explaining run_id freshness versus resuming an existing open run, and by adding the timing constraint for complete_trace that the schema alone does not state.

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: 'Open a task boundary for this session's daemon metrics.' It immediately distinguishes this from sibling tools by naming phone_run_end and explicitly excluding phone_record (video), so an agent can identify the correct tool without opening the schema.

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

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

It gives explicit pairing guidance ('pair with phone_run_end, not phone_record'), states that it is optional, and explains the fallback behavior ('without it, idle gaps infer runs'). It also covers run_id reuse semantics and the complete_trace timing constraint, leaving very 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?

The annotations only declare destructive/openWorld/non-idempotent; the description goes well beyond them by describing the execution model — whole-sequence pre-validation, a single control lock, stop-at-first-failure — and the risk semantics of retry_safe and unverified irreversible steps. It also discloses that alert-button taps are acknowledged without effect, which is a non-obvious trap an agent could not infer from the schema. Nothing here contradicts the destructiveHint=true annotation.

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 opening sentence is front-loaded with the payoff (one call, screen returned, one turn) and the constraints follow in descending priority. It is a single dense block, though; the long comma-separated enumeration of step kinds would scan faster as a list, and a few clauses (e.g. the multi_longpress finger-count restatement) duplicate schema text.

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 whose schema is a 19-variant oneOf, the description supplies exactly what the schema cannot: batching strategy, failure semantics, the safe-retry rule, and what the result reports (completed/applied counts and the failed step). With no output schema present, describing the result shape and the flow_suggestion follow-up closes the remaining 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 already 100%, so the baseline is 3, but the description adds real meaning: it enumerates the step kinds so an agent can plan a batch from the description alone, clarifies multi_longpress as 2–5 simultaneous fingers, explains drag edge-dwell, and states that these step objects are byte-identical to a saved flow's `steps`. It also names the one non-obvious workflow dependency, that `perform` needs element+snapshot from phone_elements.

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 — run a sequence of actions in one call — and immediately names the differentiator from siblings: returns the ending screen in the same reply, one turn instead of one per tap. The lead 'THE DEFAULT WAY TO ACT' plus the contrast with single-action tools lets an agent place phone_run_steps relative to phone_tap, phone_type, and phone_elements without opening any schema.

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

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

Gives explicit when-to-use ('as soon as a segment is understood') and when-not ('keep single-action tools for exploring an unknown screen'), plus hard operational rules: guard every screen change with wait_for, never batch an unverified irreversible step, and treat retry_safe=false as DO NOT replay. It also handles the follow-up branch by telling the agent to ask the user about a flow when flow_suggestion appears.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: states it takes no owner lease, wakes nothing, returns a short status with named fields (phone, drivable, owner), and degrades to no panel on non-MCP-Apps hosts. These are non-obvious side-effect and failure-mode facts the annotations cannot convey.

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

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

Purpose is front-loaded in the first clause and every sentence carries distinct information (reuse, side effects, return, exclusion, host limit). The opening sentence is somewhat clause-stacked, which costs a bit of readability.

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

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

No output schema exists, yet the description names the returned status fields, and it covers the host-compatibility caveat and the read-only/no-lease behavior. Nothing an agent needs to decide or call correctly is missing.

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

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

Schema description coverage is 100% and the single 'instance' parameter is fully documented in the schema, so a baseline 3 applies. The description adds nothing about instance selection or its "no fallback on failure" behavior beyond what the schema already says.

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

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

Specific verb+resource ("Open the live iPhone screen panel beside the chat") with the reuse semantics spelled out, and it explicitly distinguishes itself from phone_elements and phone_screenshot. An agent can tell immediately this is a UI-panel tool, not an observation tool.

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 positive trigger ("Open it once when the person wants to watch"), an explicit exclusion ("it never replaces phone_elements or phone_screenshot for your own observation"), and a host precondition ("in hosts that render MCP Apps").

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?

Beyond readOnlyHint/openWorldHint, it discloses the return payload (status, frame with mime_type and base64 data, ok, error), the private-hold behavior returning frame=null, the refusal to fabricate pixels on failed capture, and that fresh bypasses the reusable frame. That is rich behavioral context an agent cannot infer from annotations.

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

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

Four dense sentences, front-loaded with the purpose and the sibling routing before return details and usage restrictions. Information-dense with minimal waste, though the return-field enumeration is slightly list-like.

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

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

With no output schema, the description fully covers the return shape, error/empty-capture semantics, and the calling convention, leaving nothing an agent needs missing 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 coverage is 100% and the description largely restates what the schema already says (max_side clamped to 200–1000, fresh bypasses reuse). It adds little new per-parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('Internal frame transport') and immediately distinguishes itself from siblings by naming phone_screenshot for stills and phone_elements for text. An agent can identify the tool's role and its alternatives without opening any schema.

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

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

Explicit when/when-not guidance: the panel calls it with visibility app, models should not poll it from model turns, and it must not be used for health checks. It also routes to the correct siblings for image and text 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?

Beyond readOnlyHint/openWorldHint the description discloses non-obvious behavior: the frame is the settled capture reused after an observed action, overlay draws element frames with their phone_elements indexes, private holds or offline devices can refuse the call, and the ~0.9k vs ~1.5k image-token cost. The verification caveat is exactly the kind of behavioral warning annotations cannot express.

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

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

Front-loaded with the core purpose and the sibling routing before any caveats, with no filler sentences. It runs long with several semicolon-joined constraints, but each carries distinct information an agent needs.

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

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

For a read-only capture tool with no output schema, the description still states the return shape (image/png content block), the token economics, the failure modes, and the limits of what the result proves. Nothing essential for calling 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 overlay, instance, and max_side thoroughly. The description's restatement of the 1200 default and 0-for-full-resolution largely duplicates that, though tying overlay to phone_elements indexes adds a little cross-tool meaning. 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?

"Read one iPhone screen as an image/png content block when pixels matter" gives a specific verb, resource, return type, and the exact selection condition. It immediately distinguishes itself from phone_elements (text/semantic) and phone_screen (live panel), so an agent can route without opening any schema.

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

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

Explicit alternatives and their selection criteria are named: phone_elements for text/semantic targets, phone_screen for the human-visible live panel, phone_status for health checks instead of reconnecting. It also adds a scope constraint ("capture only for the current user task") and the caveat that an image alone does not prove success, with a redirect to check target state or receipt.

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

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

Annotations already declare this as non-read-only, open-world, non-idempotent, and destructive; the description adds concrete behavioral context: the prerequisite phone_status.drivable=true, the risk that a misplaced gesture can edit a control or navigate away, the travel scaling/clamping behavior, and the default observe return 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?

The description is dense but front-loaded: it begins with the core action and alternatives, then groups usage hazards, direction semantics, scaling, prerequisites, and observe behavior. Every sentence adds operational value for invoking a risky gesture correctly.

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

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

For a destructive open-world gesture tool with no output schema, the description supplies what the agent needs: alternatives, prerequisites, risky regions to avoid, direction conventions, travel scaling, and observe behavior. The annotations provide the safety profile, and the description fills in the operational details.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying that x,y are an anchor within the intended scrollable region and by explaining that travel is 1.5 times each delta in points, clamped to 15–75% of that screen dimension. Direction semantics are also reinforced, though they are already largely present in 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 action and resource: moving the viewport via one device-side swipe. It also names sibling alternatives (phone_scroll_find, phone_collect_list), so the agent can distinguish this tool from adjacent scrolling tools.

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

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

Explicitly routes known-label lookup to phone_scroll_find and multi-page reading to phone_collect_list. It also warns against swiping text fields, sliders, and screen edges, and advises inspecting the settled screen before repeating a swipe.

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

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

The description discloses real behavior beyond the annotations: immediate stop on ambiguity, covered, or not-drawn elements; no screenshot taken; swipes_confirmed counts Native ACKs rather than displacement; swipes_uncertain must not be replayed; observations withheld if ownership/privacy authorization changes. These additions are substantive, but several statements are compressed to the point of being cryptic ('Setup may already have affected the device'), so the disclosure is rich yet unevenly legible.

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 output/mode split ('Found:' / 'Not found:') is well front-loaded, but the block is a long run of terse fragments, some of which are elliptical enough to require re-reading ('Stops when ownership or privacy authorization changes and withholds observations'). A few sentences, notably the setup-affect note, lack a clear antecedent.

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 properly carries the return contract: `target` (index, kind, frame), `candidates` with index and frame, `snapshot` for phone_tap_element, plus swipes_confirmed/swipes_uncertain semantics and the app_changed refusal. It is nearly complete for a 7-parameter, open-world tool; only the ownership/privacy stop condition remains under-explained.

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, and the description does add meaning for `snapshot` (never filled in for you; a foreground app mismatch refuses before any swipe with app_changed) and for `max_swipes` (default 1). Otherwise it largely restates what the schema already documents for label, kind, region, direction, and 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?

The opening clause gives a specific verb and resource ('Find one exact label') plus the operating mode (swipe at most max_swipes times when not on screen), so an agent knows exactly what the call does. It also distinguishes itself from related siblings by naming phone_tap_element as the consumer of the returned snapshot and phone_status as a prerequisite.

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 context is strong: it warns 'absence after the budget is not proof — look at the screen before swiping further,' states the phone_status drivable=true prerequisite, and explains when a provided snapshot causes a pre-swipe refusal. It stops short of explicitly naming alternatives such as phone_scroll or phone_elements for non-label-driven 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?

Beyond annotations, the description discloses that the simulated location affects every app until cleared, that the call counts as one daemon action, that authorized device control is required, and that a transport failure leaves the effect unknown. It also advises inspecting the result and cleaning up the simulation, which is exactly the behavioral context an agent needs.

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

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

The description is front-loaded with the purpose, then gives invocation rules, side effects, failure behavior, and cleanup guidance. Every sentence contributes useful information, and there is no redundant or filler text.

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?

Although there is no output schema, the description states that it returns the applied location or clear status and notes the uncertainty on transport failure. Together with the annotations and fully described schema, this is complete enough 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 coverage is 100%, so the schema already documents the parameters, but the description adds meaningful semantics: lat and lon must be supplied together, clear=true must be used without coordinates, and combining clear with coordinates is refused. It does not add detail about the instance parameter, but the schema covers that adequately.

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: simulate GPS for testing location-aware apps. It also explicitly says the tool is not a navigation or address lookup tool, which helps an agent distinguish it from conceptually adjacent requests. The scope is clear without needing to inspect the schema.

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

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

It states the primary use case, the two valid invocation modes (lat/lon together or clear=true alone), the refusal of mixed clear and coordinates, and the need to clear the simulation when testing ends. These are explicit when, when-not, and cleanup instructions.

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

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

Annotations declare destructive/openWorld/non-idempotent, and the description adds the details that matter: receipts mean 'requested, not saved_verified', volume acknowledgement is not a level confirmation, navigation changes app state, and uncertain captures must never be replayed. This is exactly the extra context annotations cannot express, and it is consistent with destructiveHint=true.

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

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

It is a dense, run-on block rather than front-loaded clauses, and several points are stated twice – the 'requested vs saved_verified' receipt and 'check Photos before claiming saved' cover the same ground, as do 'navigation leaves the current app' and 'repeating system navigation may lose context'. Nearly every sentence earns its place, but the duplication costs it.

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

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

For a destructive, gated, open-world system-action tool with no output schema, the description covers valid inputs, refusal conditions, permission requirements, verification steps, and non-retry policy. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning about the name values: they are trimmed and case-insensitive, 'switcher' and other names fail before input is sent, and each named shortcut has documented side effects. The observe default is explained consistently in both places, which is mild redundancy.

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 enumerates the concrete shortcuts (Home, Spotlight, volume buttons, Photos screenshot) so the agent knows what the tool does despite the vague name 'shortcut'. It also distinguishes itself from phone_screenshot, phone_key, and phone_run_steps. The only weakness is that no single sentence states the purpose up front – the enumeration does the work.

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

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

Explicit routing: 'Use phone_key for field keys, or phone_run_steps with launch_app for a specific app', plus 'save_screenshot is a mutation, unlike phone_screenshot which only returns image bytes'. It also states preconditions (phone_status.drivable=true, ipu:volumeButtons, ipu:systemCaptureRequest) and what fails before dispatch.

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 readOnlyHint already covering safety, the description goes far beyond: it discloses the owner/refusal semantics (phone_owned), the full field list preserved in the JSON, the keep_runner_alive meaning, that idle release is intentional, and passcode/trust subtleties. This is substantive behavioral context annotations cannot carry.

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

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

Purpose is front-loaded, but the body is a dense wall of imperative sentences mixing routing, recovery, trust, and passcode guidance. Much is relevant, yet it's hard to scan and some prose could be compressed without losing meaning.

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

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

For a read-only status tool with no output schema, the description enumerates the returned fields and explains gating, recovery, setup, and reconnect decisions. An agent has enough to interpret results and act correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real nuance beyond the schema: 'Preserve --instance for named instances' and the no-fallback caveat, giving the agent usage guidance the schema doesn't.

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?

Opens with a specific verb and resource: 'Read the phone's status without taking control.' The 'without taking control' clause explicitly distinguishes it from the many driving/control siblings (phone_tap, phone_type, etc.).

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

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

Explicit when-to-use ('For status/health checks, report the state and stop') and when-not (reconnect only under a named set of conditions, do not loop reconnect). It also names the alternative sibling phone_reconnect and the exact preconditions for calling 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?

Adds substantial behavioral context beyond annotations: destructive effects of tapping arbitrary coordinates, prerequisite status, default observe behavior, settled screen change, and the need to read outcome/retry_safe before repeating an uncertain tap. This aligns with and enriches the destructiveHint, non-idempotent, open-world annotations.

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

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

Front-loads the core action and coordinate convention, then moves to sibling preference, prerequisites, safety warning, observe behavior, and retry guidance. Dense but every sentence earns its place 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 destructive, open-world tap tool with no output schema, the description includes prerequisites, safety expectations, observe behavior, outcome/retry_safe semantics, and guidance on inspecting state before retrying. Nothing essential for correct invocation 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 description coverage is 100%, so the schema already documents x, y, observe and instance thoroughly. The description reinforces the normalized coordinate system and observe default but does not add much parameter-level meaning beyond the schema, so baseline 3 is appropriate.

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

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

States the specific action (tap a pixel target), the coordinate system (normalized x,y from 0–1 with top-left origin), and names phone_tap_element as the preferred sibling for accessible controls. It clearly distinguishes pixel-target tapping from element-based tapping.

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

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

Explicitly says when to prefer phone_tap_element and when to use phone_screenshot to find a pixel-only target. It also states the prerequisite phone_status.drivable=true and warns that the agent must authorize the actual effect first because a tap can send, buy, delete or toggle.

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?

It explains that the daemon re-reads the tree and refuses the action if the UI changed, which adds safety context beyond the annotations. It also notes that refs are ephemeral. It does not explain why the tool is annotated destructiveHint=true, or what the refusal error 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?

Four sentences, each earning its place. The purpose is front-loaded, followed by the safety behavior, selection guidance and a persistence warning.

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?

It covers the prerequisite workflow, the staleness protection and the ephemeral refs, which is solid for a UI action tool. The return value is described only in the observe parameter. Sibling differentiation among the tap tools 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%. The description adds that the index should be chosen from the identifier/kind/label/state fields, and that element and snapshot must come from the same response. This is meaningful guidance 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?

It names a specific action (tap one element by index plus snapshot token) and ties it to phone_elements. It does not say how this differs from the siblings phone_tap (coordinates?) or phone_tap_label, so an agent choosing among the three tap tools must infer the distinction.

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 prerequisite: the index and token must come from the SAME phone_elements response. It also says how to pick the index and warns never to persist snapshot refs in a flow. It does not say when to prefer phone_tap_label or phone_tap over this tool.

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

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

Annotations only declare that this is a destructive, non-idempotent open-world write. The description adds materially: zero or multiple matches send NO action, the tap is bound to a specific phone_elements snapshot (staleness risk), and a fresh snapshot is read before acting. That is exactly the safety context an agent needs before a destructive tap.

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, then the failure contract, then the fallback path. Every clause carries either a constraint or a routing instruction; nothing is padding.

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

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

For a destructive, non-idempotent tap with no output schema, the description covers the precondition (drivable status), the failure behavior, the snapshot-binding semantics, and the observe=true return notion. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds the crucial constraint that 'label' must resolve to exactly one match, otherwise the call errors. The instance/observe parameters are left entirely to the schema, which is acceptable given full coverage.

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 ('Tap an iPhone UI element by an EXACT visible label') and implicitly separates itself from phone_tap (coordinate-based) and phone_tap_element (identifier-based). An agent can pick the right sibling without opening any schema.

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

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

Gives an explicit prerequisite ('requires drivable=true in phone_status'), the exact selection rule (one match only), and a named alternative for the ambiguous case: use phone_tap_element with the snapshot from phone_elements when labels duplicate. That is when-to-use, when-not, and where-to-go instead, all in one place.

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

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

Annotations only declare the mutation/destructive profile; the description adds substantial depth beyond them: focus can shift and text can reach the wrong field, long text is chunked at safe boundaries, tokens are single-use and scoped to field/owner/privacy/lifecycle/session, and unknown outcomes never issue a token. It also discloses partial-failure recovery via characters_confirmed and remaining_text and warns that an unknown outcome is not evidence nothing was typed.

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

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

Purpose and focus prerequisite are front-loaded, then budget/token mechanics, then failure handling and verification, in a logical order with no filler. It is dense and telegraphic to the point that a couple of clauses (token scoping dimensions) read as enumerated keywords, but every sentence conveys operational information.

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

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

For a destructive, non-idempotent, open-world typing tool with no output schema, the description covers what an agent needs before and after invocation: precondition gating, chunking and continuation, partial-failure inspection fields, and a verification instruction before submitting. Nothing material to calling 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 relational meaning the per-parameter descriptions do not carry on their own: the budget_ms/continue_token protocol, the incompatibility of tokens with text/clear/budget_ms, and the meaning of an absent token on unknown outcome. It does not spell out the `instance` or `clear` selection semantics, keeping 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 a specific verb and resource ('Insert literal Unicode text into the currently focused iPhone field') and immediately distinguishes itself from phone_tap_element (focusing) and phone_key (navigation/editing keys). An agent can tell exactly what this tool does versus its siblings without opening any schema.

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

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

Explicitly names the precondition sequence (focus with phone_tap_element first), the alternative for keys (phone_key), and the gating requirement (phone_status.drivable=true). It also states the continuation path for budget_ms and the prohibition on reusing text/clear/budget_ms with a token, which is genuine when/when-not guidance.

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