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

Annotations already cover readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is mostly established. The description adds a small behavioral rationale about reliability but doesn't detail side effects like global clipboard mutation or overwriting existing clipboard content. With annotations present, this is adequate but not rich.

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

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

Two short sentences, front-loaded with the action, followed by a useful rationale. No wasted words and every sentence earns its place.

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

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

For a simple two-parameter tool with output schema and annotations, the description is sufficiently complete. It could explicitly point to ios_type or ios_read_text for comparison, but the clipboard scope is clear enough that nothing critical 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 schema already explains 'text' and 'action' clearly. The description adds no parameter-level detail beyond what the schema provides. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description names a specific verb and resource: 'Read or write the device clipboard.' This is clear and unambiguous. It doesn't explicitly distinguish itself from sibling tools like ios_type or ios_read_text, but the resource ('clipboard') makes the scope evident.

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

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

The description provides a concrete usage pointer: writing is faster and more reliable than typing a long string because the keyboard can mangle with autocorrect. This gives the agent a clear reason to choose clipboard writes for long text. It doesn't mention explicit exclusions or alternatives by name, so it falls short of full routing guidance.

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

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

Annotations already indicate a mutating, externally visible, idempotent operation that is not destructive. The description adds useful context about what gets affected (device and WebDriverAgent runner), but does not go beyond that to describe edge behaviors such as effects on running apps or session cleanup details.

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, direct sentence that front-loads the action and target. Every word earns its place, with no filler or redundant restatement of the tool name.

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

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

For a zero-parameter, low-complexity tool with output schema and annotations available, this description fully conveys what the operation does. An agent can correctly select and invoke the tool based on this definition.

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 has zero parameters and the schema documents this fully with 100% coverage. The baseline for a zero-parameter tool is 4, and the description adds no contradictory or missing parameter semantics.

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 specific verbs ('release', 'shut down') tied to a clear resource (the device and its WebDriverAgent runner). It directly identifies the tool as the closing counterpart to ios_open_session and is distinguishable from siblings like ios_halt and ios_resume.

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

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

The description implies the tool is used when a session should be ended and the device released, but it does not explicitly state when to use it versus alternatives like ios_halt or ios_open_session. The usage context is inferable but not stated outright.

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 tool read-only, non-destructive, and idempotent. The description adds meaningful behavioral information: it is a diagnostic preflight that provides concrete remedies for every failing check. This tells the agent what kind of output to expect and reinforces a safe, non-mutating 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 compact, front-loaded with the core purpose, and every sentence adds value. The second paragraph gives concrete usage triggers, and the final clause sets expectations for the output. There is no fluff or repetition of structured metadata.

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 zero parameters, existing output schema, and comprehensive annotations, the description is complete. It covers what the tool does, when to run it, how it fits into the workflow, and what kind of result it produces. Nothing essential is missing for an agent to invoke 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?

The tool has no parameters, so the description has no parameter semantics to convey. The schema fully documents this with an empty properties object. A baseline of 4 is appropriate because no additional parameter meaning is needed.

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 ('Check') and a clear resource ('that this machine can drive an iOS device'), and states the output ('say how to fix what it can't'). This cleanly distinguishes the tool from diagnostic siblings like ios_list_devices or ios_session_status, which focus on device presence or session state rather than host readiness.

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

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

The description explicitly says when to run this tool: when a session fails to start, when a device does not appear, or after an Xcode/iOS upgrade. 'Run this first' also gives ordering guidance. It does not explicitly name excluded alternatives, but the conditional triggers are clear enough.

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 indicate this is a non-read-only, non-destructive mutation. The description adds that it performs a drag gesture and results in moving or reordering UI elements, which is useful context beyond the raw annotations. It does not go deeper into side effects, prerequisites, or failure behavior, but the annotation coverage lowers the burden.

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

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

A single sentence with no filler. It front-loads the core behavior and immediately follows with the practical purpose, making every word earn 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?

Given the rich input schema (all parameters documented), the presence of an output schema, and annotations covering safety and mutation profile, the description is complete enough for an agent to invoke this tool correctly. It provides the essential semantic framing without needing to restate schema 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?

The input schema has 100% parameter description coverage, so the schema already explains from_ref, to_ref, idem_key, and duration_s. The description's 'one element onto another' mirrors the from_ref/to_ref relationship but adds no extra semantics for the optional parameters. 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?

The description states a specific verb ('Drag') and resource ('one element onto another'), plus the intended use cases ('reordering lists and moving items'). This clearly distinguishes it from sibling gesture tools like ios_swipe and ios_tap, which do not involve a source and destination element pair.

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 provides clear context for when to use the tool: reordering lists or moving an item to a target location. It does not explicitly name alternative tools or state when not to use it, so it lacks full exclusion guidance, but the element-to-element semantics make the use case 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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context by specifying the output is an ordered record of the session's actions, which is more specific than the 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?

The description is two short sentences with no filler. The first sentence states the core behavior, and the second provides practical use cases, making it easy to scan.

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 a zero-parameter schema, rich safety annotations, and an output schema available, this description is sufficient for call selection and invocation. It explains what the tool returns, why it is useful, and leaves no critical 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?

The tool accepts zero parameters, so parameter guidance is unnecessary. The description doesn't need to compensate for schema gaps because there are no parameters to document.

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: 'Return the ordered record of everything this session has done.' This clearly differentiates from sibling tools like ios_session_status or ios_get_logs by emphasizing a chronological, session-scoped history.

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

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

The description gives explicit use cases: explaining what happened and converting a successful run into a regression test. It does not state when not to use it or name alternatives, but the context is clear enough for an agent to select it appropriately.

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 cover the safety profile: readOnlyHint, idempotentHint, and destructiveHint=false. The description adds only the troubleshooting context, not additional behavioral details. Since the annotations carry most of the load, this is adequate but not enhanced.

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 consists of two short sentences with no redundant wording. The core action is front-loaded ('Read recent device logs') and the usage context is stated in the next sentence, making it easy to scan.

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

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

For a simple read-only tool with three optional parameters, an output schema, and strong annotations, the description supplies enough purpose and usage context. It is complete for selection, and the schema handles invocation 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?

The input schema covers all three parameters (limit, since_s, predicate) with descriptions, giving 100% coverage. The tool description adds no extra parameter context, so a 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?

The description clearly states the verb and resource: 'Read recent device logs.' This is specific enough to identify the tool's function, but it does not explicitly differentiate itself from sibling tools like ios_export_trace, which may also deal with device-level data.

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

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

The description gives clear usage context: 'Useful when an app misbehaves and the UI does not say why.' This helps an agent understand when to choose this tool, though it does not mention when not to use it or name any alternative diagnostics 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 convey idempotent=true, readOnly=false, and destructive=false, lowering the burden on the description. The description adds some behavioral context by saying the session stops taking further action, but it does not disclose whether the session can be resumed, what happens to pending tasks, or any side effects. No contradiction with annotations was found.

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

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

The description is a single sentence with no filler. It is front-loaded and every word carries meaning, especially the phrase 'from taking further action', which distinguishes halting from closing or resuming.

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 this simple, the description is mostly sufficient, especially with annotations and an output schema present. However, it leaves out whether the action is reversible and how it relates to ios_resume or ios_close_session, which are important contextual cues for an agent choosing between sibling tools.

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 schema covers both the reason parameter and its default value with 100% coverage, so the description does not need to add parameter detail. The description adds no additional meaning about the 'reason' field, but the baseline of 3 is appropriate because the schema already documents it fully.

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 ('Stop') and resource ('this session') and states the effect ('from taking further action'). It is clear about what the tool does, though it does not explicitly contrast itself with sibling tools like ios_close_session or ios_resume, so it is not fully self-differentiating.

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

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

The description gives no guidance on when to use this tool versus alternatives such as ios_close_session or ios_resume. There is no mention of situations where one should close the session instead of halting it, nor whether this action is pause-like or final.

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 indicate destructiveHint=true and readOnlyHint=false, but the description adds important behavioral context by explaining that accepting can 'grant a permission or confirm a deletion nobody wanted.' This warns the agent about real consequences and complements the structured annotation without contradicting it.

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

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

The description is two sentences with no wasted words. The first sentence states the core action front-loaded, and the second provides a high-value caution that directly affects agent behavior. Every phrase earns its place.

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

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

For a two-parameter tool with an output schema and annotations covering destructive behavior, the description is largely complete. It conveys the essential decision-making context and warns of risks. A minor gap is not explicitly stating the trigger condition ('when an alert appears'), but that is reasonably inferred from the tool name and purpose.

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%: action is documented as 'accept' or 'dismiss' and button as the exact label when several exist. The description adds no additional parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with 'Answer a system alert,' a specific verb plus resource that immediately identifies what the tool does. It is clearly distinct from sibling tools like ios_tap, ios_launch_app, or ios_set_permission, which handle different actions. The warning about accepting blindly reinforces the purpose without obscuring it.

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 instruction to 'read the alert text before choosing' implies the appropriate moment to use this tool: when a system alert appears and a decision is needed. It offers no explicit alternative or exclusion, but none of the sibling tools are natural alternatives for answering alerts, so the guidance is sufficient for correct use.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation is expected. The description adds the local-source constraint but does not disclose potential side effects like overwriting an existing app or requiring a signed bundle. This is acceptable but not rich.

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

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

A single sentence with no filler. It is front-loaded with the verb and object, and every word contributes useful information.

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

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

For a one-parameter tool with a complete schema, output schema, and annotations, the description is largely sufficient. It identifies the input type and source. Minor caveats about device state or signing are absent, but they are not necessary for basic 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 path parameter is already well documented. The description adds the 'local' qualifier and confirms the accepted file types, but does not meaningfully expand 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?

The description clearly states the verb 'Install', the resource 'app', and the source 'local .app or .ipa'. It is immediately distinguishable from sibling tools like ios_launch_app and ios_terminate_app.

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

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

The description implies installation is for local app bundles and .ipa files, but it does not explicitly discuss when to use this tool vs alternatives or state exclusions. The 'local' qualifier gives some contextual guidance, but no explicit routing or prerequisites are provided.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description doesn't need to restate that. It adds that launching brings the app to foreground and returns a screen, but doesn't disclose side effects around app restart behavior, waiting, or error cases if the app isn't installed.

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

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

The description is a single, front-loaded sentence with no filler: it names the action, the object, and the result. Every word contributes to the agent's understanding.

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

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

For a simple two-parameter tool with a complete input schema, annotations, and an output schema, the description is mostly sufficient. The only notable gap is the lack of behavior on failure (e.g., missing bundle_id app) and how it interacts with currently running apps, but these are minor given the schema and output schema coverage.

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

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

Schema description coverage is 100%, with both bundle_id and fresh documented. The description adds no parameter-level detail beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the action ('Bring an app to the foreground') and the expected outcome ('return its screen'), and the tool name reinforces this. It distinguishes itself from siblings like ios_terminate_app and ios_install_app, though it doesn't explicitly distinguish 'return its screen' from ios_screenshot.

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

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

The description gives no guidance on when to use this tool versus alternatives such as ios_open_url, ios_install_app, or ios_screenshot. There are no exclusions, prerequisites, or context hints beyond restating the action itself.

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 communicate that the operation is read-only, idempotent, and non-destructive. The description adds that it enumerates installed apps and exposes bundle identifiers, but it does not disclose potential caveats such as the default 'user' filter or permission requirements. This is acceptable but not rich.

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

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

A single sentence that is front-loaded with the action and resource, contains no filler, and immediately tells the agent what the tool does and what information it provides.

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?

Tool complexity is low: one optional, fully documented parameter; annotations describe safety; and an output schema exists. The description is complete enough for a straightforward read-only enumeration. The main missing piece is usage guidance, already penalized under that dimension.

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 only parameter, 'kind', has 100% schema coverage with a clear description of 'user', 'system', or 'all'. The tool description itself adds no extra parameter-level meaning, so the baseline of 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?

Uses a specific verb ('List') with a clear resource ('apps installed on the device') and explicitly mentions the bundle identifiers returned. This distinguishes it from sibling tools like ios_list_devices, ios_launch_app, and ios_install_app without requiring schema inspection.

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

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

The description does not state when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. An agent is not told, for example, that this is useful for discovering bundle identifiers before launching an app, and no alternative tools are referenced.

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, openWorldHint, idempotentHint, and destructiveHint=false, and the description does not contradict them. The description adds useful context by explaining that `ready` indicates automation blockers and `blockers` details them. This goes beyond what annotations alone 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?

Two concise sentences with no filler. The primary action is front-loaded, and the second sentence adds a valuable clarification about output semantics. Every word earns its place.

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

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

With an output schema, full parameter schema coverage, and comprehensive annotations, the definition is operationally complete. The `ready`/`blockers` note addresses the only non-obvious interpretation of the result. Nothing an agent needs to correctly select and invoke this tool 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?

The schema fully describes the only parameter `kind`, including its default value and filter options, so schema coverage is 100%. The description adds no additional parameter-level detail. Baseline 3 applies because the schema carries the semantic load.

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: lists iOS simulators and attached physical iPhones. The second sentence clarifies `ready` and `blockers`, giving additional meaning to the output. It is clearly distinct from sibling tools like ios_doctor or ios_session_status.

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

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

The phrase 'available for automation' implies this is used for discovering devices before automation, but there is no explicit when-to-use or alternative guidance. No sibling tool performs the same listing, so the lack of exclusions is less critical. Guidance remains implicit rather than explicit.

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 the tool read-only, idempotent, and non-destructive. The description adds value by disclosing the compact line format, the ref-versus-coordinate convention, and the truncation behavior with concrete recovery advice. Nothing in the description contradicts the 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?

Three short paragraphs each serve a distinct purpose: define the output format, explain how to use the refs, and explain how to handle truncation. The example is compact and the most actionable information is front-loaded. There is no redundant or filler content.

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 the output schema, full parameter coverage, and strong annotations, the description supplies the key behavioral context that is not in those structured fields: ref format and truncation recovery. It is nearly complete; explicit differentiation from ios_read_text or ios_screenshot would make it fully self-contained for tool selection.

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 for parameters is 100%, so the baseline is 3. The description adds cross-parameter guidance by explaining that query and region are the right ways to narrow a truncated result and that raising budget is not the recommended fix. This goes beyond the individual schema descriptions.

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

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

The description names a specific action and resource: 'Read the screen as a compact list of elements with short refs.' It also clarifies the output's unique role by saying refs should be passed to action tools instead of coordinates, which helps separate this from screenshot or text-reading tools. It does not explicitly name sibling tools, but the ref-based interaction model makes the tool's purpose reasonably distinct.

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 clear operational guidance: when elements are omitted, narrow with query or region rather than raising budget. This also implies the tool is meant for obtaining reusable refs before invoking action tools. It stops short of explicitly contrasting this tool with ios_read_text or ios_screenshot, so it does not fully explain when to choose this over those alternatives.

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

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

Beyond the annotations, the description reveals important side effects: it boots the simulator or verifies the phone, starts WebDriverAgent, and opens a tuned session. The explicit note about default device preference — preferring a booted simulator over a connected iPhone — adds valuable behavioral nuance not available from annotations or 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?

The description is compact, front-loaded with the core purpose, and every sentence adds value: one for overall intent, one for mechanism, and one for a critical selection caveat. No filler or redundancy.

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

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

Given a fully described input schema, an output schema, and annotations that cover idempotency and side-effect hints, the description supplies the remaining operational context: setup steps and device-selection behavior. Nothing essential for an agent to correctly invoke and interpret this tool 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?

The schema already provides 100% description coverage for all three parameters, so the baseline is strong. The description adds meaningful semantics for `device` by explaining how the default is chosen, which is not fully specified 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?

The description leads with a specific action and resource: 'Attach to a device and start driving it.' It then details the concrete steps (boots simulator/verifies phone, starts WebDriverAgent, opens a tuned session), which clearly identifies it as the session-opening tool and distinguishes it from the interaction and lifecycle sibling 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?

It provides clear context that this tool is the entry point for driving a device and explains the device-selection behavior. It does not explicitly name alternatives or exclusions, but the intended use is strongly implied by the first sentence and the device-preference caveat.

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 the tool as idempotent and non-destructive. The description adds practical context by noting deep links skip navigation, but it does not disclose potential behavioral side effects such as switching apps or leaving the session context. Given the annotation coverage, this is adequate but not richly transparent.

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

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

Two compact sentences with no filler. The first sentence states the operation directly, and the second adds decision-relevant cost guidance. Every sentence earns its place.

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

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

For a tool with one well-documented parameter, an output schema, and annotations covering safety and idempotence, the description is complete enough. An agent knows what to pass, what the tool does, and when to prefer it over manual UI navigation.

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 single parameter is fully documented in the input schema, including type and examples. The description merely restates 'URL or deep link' and does not add new parameter-level meaning. With 100% schema description coverage, the baseline of 3 applies.

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

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

The description opens with a concrete verb and resource: 'Open a URL or deep link.' It also positions the tool as the 'cheapest way to reach a screen,' which helps distinguish it from tap-driven navigation tools like ios_tap and ios_launch_app, though it does not explicitly name a sibling alternative.

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

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

The description provides a clear heuristic: prefer a deep link to avoid navigating through taps. It explains the benefit of using this tool ('skips the navigation') but does not mention cases where this tool should not be used or name explicit alternatives, so it falls short of a 5.

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

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

Annotations already disclose readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the core behavioral profile is known. The description adds no extra behavioral context such as likely side effects of pressing home or siri, but it is consistent with the annotations and therefore not misleading.

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

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

The description is a single, efficient sentence with no filler. It clearly front-loads the core action, though it is arguably too sparse to fully stand alone without 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 simple two-parameter tool with a complete input schema, output schema, and relevant annotations, the one-sentence description covers the essential action. The only significant gap is usage guidance, which is already captured under usage_guidelines.

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%, fully documenting accepted values for 'name' and the purpose of 'idem_key'. The description itself adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Press') and a specific resource ('hardware button or keyboard key'), making the tool's purpose immediately clear. It inherently distinguishes itself from sibling touch-based tools like ios_tap, ios_type, and ios_swipe.

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

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

No guidance is provided about when to use this tool versus alternatives such as ios_tap or ios_type. There are no exclusions, no context, and no mention of scenarios where pressing a hardware button is preferable.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds the scoping behavior (screen vs element subtree) but does not disclose additional behavioral details beyond what the annotations and schema already 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?

Two concise sentences carry the essential purpose, scope, and usage contrast with zero filler. The key action is front-loaded.

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

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

For a simple read-only tool with two optional params, rich annotations, and an output schema, the description covers everything an agent needs to invoke it correctly. The sibling contrast removes ambiguity about when to use it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds slight context by referring to 'one element and everything inside it,' but the parameter meanings are already well documented 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?

The description states a specific action ('Read the text of the screen, or of one element and everything inside it') with a clear resource scope. It also explicitly contrasts itself with ios_observe, making it easily distinguishable from the most similar sibling.

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

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

It provides explicit usage guidance: use this tool to extract content, and avoid ios_observe when the goal is deciding what to tap. This directly tells the agent when to choose this tool over an alternative.

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 indicate idempotency and non-destructiveness. The description adds meaningful behavioral context: this tool clears a halted state and requires human authorization to proceed, which is beyond what the annotations or empty schema provide.

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, well-constructed sentence that communicates both the action and the safety condition with no wasted words.

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

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

For a zero-parameter tool with an output schema and annotations covering idempotency and safety, the description fully explains when and why to call it. Nothing necessary for correct invocation 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?

The tool has zero parameters and the schema description coverage is 100%, so the baseline is 4. The description needs no parameter details and none are missing.

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

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

The description states a specific action ('Clear a halt') and resource, making it immediately clear that this tool resumes an operation that was previously halted. This also distinguishes it from its sibling ios_halt, which presumably performs the halt.

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

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

The description gives a clear condition for use: only after a human has decided it is safe to continue. It does not explicitly name ios_halt as the alternative, but the opposite action is strongly implied by the phrasing and sibling context.

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

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

Annotations already mark the action as read-only, idempotent, non-destructive, so no safety disclosure is needed. The description adds useful behavioral context beyond that: screenshots are needed for visual/layout scenarios, and annotate_refs labels boxes with refs from the last observation, which tells the agent how to exploit the output for follow-up actions.

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

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

Three sentences, no filler. The core purpose is first, the usage guidance is second, and the only parameter's behavioral effect is explained third. Every sentence earns its place and the length is proportionate to the tool's simplicity.

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 screenshot tool with one optional boolean and strong read-only/idempotent annotations, the description fully covers what the tool does, when to reach for it instead of ios_observe, and what annotate_refs does. No critical missing information remains for correct selection and 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?

The sole parameter annotate_refs is already fully described in the schema (draw numbered boxes over elements from the last observation). The description repeats this in different words and adds the rationale 'so you can pick one by eye', but does not materially expand the schema's definition. With 100% schema description coverage, 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?

The description states a specific verb and resource ('Capture the screen as an image') and immediately distinguishes this tool from ios_observe by explaining when it is needed: missing accessibility labels, layout concerns, or things visible but not observable. This makes the tool's identity and boundary clear.

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 conditions for use: when an element has no accessibility label, when layout matters, or when ios_observe cannot find something visible. It also names the alternative ios_observe, giving the agent enough to choose correctly without needing further context.

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

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

The annotations are neutral, so the description carries the behavioral disclosure. It adds valuable context: scrolling stops as soon as the text appears, gives up when content stops moving, and avoids spinning at the end of a list. This is exactly the kind of runtime behavior an agent needs to know and is not present in the 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?

The description is two short sentences with no filler. The core action is front-loaded, and the second sentence supplies critical termination behavior. Every word earns its place.

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

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

The tool is simple, the input schema is fully documented, and an output schema exists. The description covers the main purpose, the optional stopping condition, the give-up behavior, and the anti-spin guarantee. Nothing essential is missing for an agent to call this tool confidently.

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 input schema already describes all six parameters, so the baseline is 3. The description adds meaningful semantic detail to the `until` parameter by defining both the success condition and the give-up condition, clarifying what the agent should expect. This goes beyond the schema's terse 'Keep scrolling until this text appears.'

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 clearly states the action ('Scroll') and its optional goal ('until some text comes into view'). It is specific enough about the tool's behavior, but it does not explicitly distinguish ios_scroll from sibling ios_swipe, which might also scroll content.

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

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

The description implies usage through the `until` option and explains when scrolling stops, giving the agent a sense of when to use it. However, it does not explicitly state when to prefer this tool over alternatives like swipe, drag, or wait_for, nor does it mention when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the specific pieces of information returned, but does not disclose potential prerequisites such as requiring an open session or error behavior when no session exists. This is acceptable given the simple read-only nature, but no extra behavioral context is provided.

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

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

The description is a single sentence with the verb front-loaded ('Report') followed by a concise, scannable list of reported fields. Every word adds value, and there is no redundant or filler content.

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

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

For a zero-parameter, read-only tool with an output schema available, the description provides sufficient context to select and invoke the tool. It states the exact scope of the report, and the output schema can handle any detail about return values. Nothing essential 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?

The tool has zero parameters and schema description coverage is 100% by definition. The description correctly omits parameter details as there are none to explain, matching the baseline of 4 for parameterless tools.

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 ('Report') and resource ('current session'), then enumerates the key contents (device, foreground app, safety state). This clearly differentiates it from siblings like ios_open_session, ios_close_session, and ios_launch_app by indicating it is a read-only status query.

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

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

The description clearly implies when to use this tool: whenever the current session details are needed. It does not explicitly mention alternatives or exclusions, but the read-only reporting context is unambiguous, especially compared to mutation-focused siblings like ios_set_device_state or ios_set_permission.

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 provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false, covering the basic safety profile. The description adds the simulator-only behavioral constraint, which is useful, but it does not explain side effects, persistence, or what happens if the tool is invoked on an unsupported device. It does not contradict the 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?

The description is two short, purposeful sentences. The primary action and the most important constraint are front-loaded, and there is no filler or repetition of schema content. It is an appropriately sized definition.

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

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

The description is sufficient for a simple optional-parameter state-change tool, and the output schema plus annotations cover many aspects. However, it leaves ambiguity about whether 'orientation' is also simulator-only, and it does not explain behavior on physical devices. These gaps make it adequate but not complete.

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

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

Schema description coverage is 100%, so the input schema already documents every parameter. The description's mention of 'Appearance, location, and status bar' loosely corresponds to parameters, but it does not add details beyond the schema. Baseline 3 is appropriate because the schema carries the semantic load.

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 clear verb ('change') and a resource ('device-level state'), and it enumerates specific concerns (appearance, location, status bar) that map directly to the input schema. It is distinguishable from siblings like ios_set_permission or ios_launch_app, though it does not name them. The resource phrase is slightly generic, preventing 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?

The description provides an important usage constraint: 'Appearance, location, and status bar are Simulator only.' This tells the agent not to attempt those changes on physical devices, but it does not explicitly identify when to prefer this tool over alternatives or mention any exclusion criteria. Usage context is implied rather than fully 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?

The description adds meaningful behavior beyond annotations: it operates 'without going through the alert' and is limited to the simulator, which are not captured by readOnlyHint or idempotentHint. It does not detail every effect on existing permissions, but the idempotentHint annotation already covers repeat-safety. This is a good balance of added context and annotation reliance.

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

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

Two sentences, no wasted words. The core function is front-loaded in the first sentence, and the second sentence delivers the critical constraint and alternatives. Every element earns its place.

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

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

For a simple mutation tool with a complete input schema and an output schema present, the description covers the essential context: the operation, the platform restriction, and how to handle real devices. There is no missing information an agent needs to select and invoke 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 description coverage is 100%, with each parameter already documented (grant boolean, service allowed values, bundle_id purpose). The tool description adds no additional parameter-specific meaning, so the baseline of 3 is appropriate for a schema that fully carries the parameter semantics.

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 clearly states the action and resource: 'Set a privacy permission without going through the alert.' This specific verb+resource combination immediately distinguishes it from alert-handling and other iOS control tools. The simulator-only note further narrows scope, making the tool's purpose unambiguous.

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

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

Explicit usage guidance is provided: 'Simulator only. On a real phone there is no API for this: drive the Settings app, or answer the permission alert with ios_handle_alert.' This directly tells the agent when to use this tool and which alternatives to choose on real hardware, leaving no ambiguity.

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 indicate the tool is destructive and not read-only, and the description adds meaningful behavioral context beyond those annotations: it checks the current state before acting and avoids an unintended toggle. This is valuable non-obvious behavior that helps the agent predict outcomes, though it does not elaborate on broader side effects.

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 only two sentences: the first states the purpose, and the second explains the key behavioral advantage. Every sentence earns its place, and the most important guidance is front-loaded.

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

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

Given the annotations, full schema coverage, and output schema, the description provides sufficient context for correct invocation. It clearly identifies the supported control types and the state-checking behavior. A small gap is that it does not explicitly mention when tapping might still be the better choice, but that is a minor omission and partially covered by the usage guidance.

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 the parameters. The description mainly reiterates the 'value' concept without adding new parameter-level detail; it does not need to compensate because 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?

The description uses a specific verb ('Set') and explicitly lists the target resource types ('switch, slider, stepper, or picker'), making it immediately clear what the tool does. It also distinguishes itself from the tap alternative by explaining why it is preferred for switches.

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

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

The description directly advises preferring this tool over tapping a switch and explains the behavioral reason: it checks current state first, so asking for 'on' when already on results in no action. This gives the agent a clear decision rule for when to choose this tool over its sibling, ios_tap.

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 cover read-only, idempotent, and destructive hints, so the description doesn't need to restate safety. The phrase 'Swipe once' adds one-shot gesture semantics, but the description doesn't detail side effects like navigation or reveal behavior beyond that.

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

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

The description is a single, front-loaded sentence with no wasted words. It communicates action, scope, and usage contexts efficiently.

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

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

For a low-complexity gesture tool with a complete schema, annotations, and an output schema, the description provides sufficient orientation. A more explicit boundary against ios_scroll would make it fully complete, but that's a minor gap.

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

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

Schema description coverage is 100%, so the parameters are already documented with meaningful descriptions. The tool description adds no parameter-level guidance, which matches the baseline for fully covered schemas.

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

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

The description names a specific gesture ('Swipe once') and scopes it to concrete UI contexts (carousels, page views, swipe-to-reveal rows), which differentiates it from siblings like ios_scroll and ios_drag in practice. It doesn't explicitly name another tool, but the use-case list provides clear enough purpose.

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

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

The description gives clear contexts where the tool is appropriate, so an agent can infer when to select it over similar gesture tools. It stops short of saying when not to use it or naming alternatives, so it doesn't reach the explicit when/when-not bar.

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 the description adds useful behavioral context by explaining that taps on actions like Send, Pay, or Delete require approval first. This gives the agent a concrete sense of the tool's risk profile beyond the raw 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 description is appropriately short and front-loaded: the core purpose is stated in the first sentence, followed by two high-value usage warnings. Every sentence earns its place with no redundancy.

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

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

Given the tool's 7 optional parameters, destructive annotation, and output schema, the description covers the key decision points: what it does, what it returns, how to identify the target, and when extra approval is needed. It stops just short of being fully complete by not contrasting with sibling interaction tools, but that is a minor 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 100%, so the baseline is 3. The description enhances this by explaining why `ref` is preferred over `target`—it is exact and cannot be misread—and by tying approval requirements to certain tap targets, which is not evident from the schema alone.

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

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

The description clearly states the action ('Tap an element') and the result ('return the resulting screen'), identifying the specific resource and behavior. It is distinct from sibling tools like ios_press_button or ios_type, which target different interaction styles.

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

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

The description gives practical guidance on preferring `ref` over `target` and warns about approval-required taps, which helps with invocation. However, it does not explicitly explain when to choose this tool over alternatives like ios_press_button, ios_scroll, or ios_type, so the usage context is implied rather than fully 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?

Annotations already declare readOnlyHint=false and idempotentHint=false, and the description adds no meaningful behavioral detail beyond the word 'force-quit.' It does not mention potential loss of unsaved state, behavior on already-terminated apps, or side effects. The description carries little weight beyond the 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?

The description is one short sentence with no fluff, and it is front-loaded with the core action. It is appropriately brief for such a simple tool, though it sacrifices substance for brevity.

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 the low complexity, single parameter, complete schema coverage, and present output schema, the sparse description is nearly sufficient to invoke the tool correctly. However, it lacks usage context, error conditions, or any note about consequences, leaving the agent to rely on annotations and inference.

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 bundle_id parameter is well documented in the schema, so the description does not need to add parameter details. The description also provides no additional parameter context, matching the baseline for fully covered schemas.

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

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

The description 'Force-quit an app' clearly identifies a specific verb and resource, making it unmistakably different from tools like ios_launch_app or ios_halt. It does not explicitly distinguish itself from siblings, but the action and target are unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives, nor any conditions or exclusions. An eggent must infer from the tool name and siblings that this is for terminating an app; no context is provided.

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 signal destructiveHint=true and readOnlyHint=false, so the mutating nature is covered. The description adds a useful behavioral detail: it focuses the field first when a ref or target is given. This goes beyond the structured annotations and aligns with 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?

The description is a single sentence with no wasted words. The core action is front-loaded and the focusing condition is stated efficiently.

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

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

With a complete input schema, output schema, and annotations, the description does not need to repeat parameter or return details. The only notable gap is that the password-related routing to ios_type_secret is not surfaced in the tool description itself, but it is present in the schema.

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 value by specifying that focusing happens first when a ref or target is provided, which describes the interaction between those parameters. Other parameter details are already well documented 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?

The description uses a specific verb and resource: 'Type into a field', and adds the focusing behavior when a ref or target is given. This makes the tool's basic purpose clear. It does not, however, explicitly differentiate itself from sibling tools like ios_type_secret or ios_set_value within the description itself.

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

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

The description implies use for typing into a field and clarifies the ref/target focusing condition, but it does not explicitly say when to prefer this over ios_type_secret (for passwords) or ios_set_value. The password guidance appears only in a parameter description, not in the tool description.

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 adds meaningful behavioral context beyond the annotations: the secret is read from the host keychain, sent directly to the device, and never enters the transcript. This is valuable security-relevant information that annotations do not capture. It slightly falls short of a 5 because it doesn't mention potential keychain access prompts or failure behavior if the secret is missing, but the annotations already cover the general safety profile.

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

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

The description is compact and front-loaded: the key benefit ('without ever seeing its value') is stated first, followed by the operational flow and the critical usage rule. Every sentence earns its place with no filler or redundancy.

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

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

Given the presence of a comprehensive input schema, output schema, and annotations, the description covers the essential security context and usage boundaries. It clearly explains the tool's purpose, data flow, and the main alternative, which is sufficient for an agent to select and invoke the tool correctly. No critical missing information was found.

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 input schema provides 100% parameter description coverage, so the description does not need to repeat parameter semantics. The description does add a high-level hint that secret_ref is a secret name rather than a value, but the schema already states this explicitly. Thus the baseline score of 3 applies.

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

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

The description clearly states a specific action ('Type a stored secret') and a distinguishing behavior: it never reveals the secret value and reads it from the host keychain. This immediately separates it from the sibling `ios_type` tool, which is the main alternative.

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

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

The description explicitly says when to use this tool ('for every password and one-time code') and when not to use `ios_type` ('never put a real credential into `ios_type`'). It names the sibling tool and gives a clear routing rule, leaving no guesswork for the agent.

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 adds meaningful behavioral detail beyond the annotations: it returns as soon as the condition holds, and it reports failure rather than raising an exception, making timeouts more predictable. This is genuinely useful context for an agent reasoning about execution outcomes.

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 short, front-loaded with the core purpose, and every sentence earns its place. It states what the tool does, when to prefer it, and how it behaves on timeout without wasting words.

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

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

For a simple tool with full schema coverage, rich annotations, and an output schema, the description covers all the behavioral information an agent needs to select and invoke it correctly. The only minor gap is sibling differentiation, but that is not essential given the clarity of the description.

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?

All three parameters are fully documented in the input schema, so the description does not need to repeat them. The description adds contextual meaning around waiting and timeout behavior but does not add parameter-level details 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?

The description clearly states a specific action and resource: waiting for something to appear or disappear. It is not a tautology and gives the core function, but it does not explicitly differentiate this from sibling tools like ios_observe or ios_read_text.

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

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

The description gives clear usage context by saying 'Prefer this over guessing a sleep' and explains the advantage: it returns as soon as the condition holds. It does not list exclusions or alternative tools beyond the sleep comparison, so it is not a full when-to-use guide.

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