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

The annotations indicate only that the tool is not read-only; the description adds that get_text is a read operation while accept/dismiss mutate the alert. However, it does not disclose behavior such as what happens when no alert is present, whether accept/dismiss consume the alert, or edge cases involving buttonLabel.

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

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

A single front-loaded sentence with no filler. It conveys the resource and the three action modes without wasting words, making it easy to scan and parse.

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 three-parameter tool with no output schema, the description plus schema is nearly sufficient; 'read alert text' reasonably implies the return value. Still, it does not specify return details or no-alert/error behavior, so it stops just short of fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters including the action enum and buttonLabel. The description mostly restates those values, adding only the semantic framing of get_text as reading alert text, which provides marginal extra value.

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

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

The description names the target resource (system alerts) and enumerates the exact operations: accept, dismiss, or get alert text. This makes it clearly distinguishable from generic text tools such as appium_get_text, despite 'handle' being a generic verb.

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

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

The description establishes a clear trigger condition: use this tool when a system alert must be accepted, dismissed, or its text read. It does not explicitly name alternative tools or state when not to use it, but the alert-specific scope makes routing an agent straightforward.

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 readOnlyHint=false and openWorldHint=true. The description does not disclose that several actions are destructive (uninstall, clear), that a confirmToken workflow gates repeats, that some actions require id/name, or that inputs resolve on a remote Appium server. For a mutation-heavy tool, this leaves most behavioral burden undocumented in the description text.

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

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

It is a single, front-loaded sentence with no filler, which is structurally clean. But the brevity comes from under-specification rather than efficient communication; the sentence reads as a topic list rather than an actionable 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?

This is a 13-parameter, 10-action mutation tool with no output schema and minimal annotations. The description omits confirmation requirements, destructive-action warnings, required-parameter distinctions per action, and session scoping, leaving it far from complete for the complexity involved.

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 id, path, action semantics, seconds, confirmToken, and other parameters in detail. The description adds no parameter meaning beyond the generic topics "state, data, and deep links," so it sits at the baseline for fully documented 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?

"Manage app lifecycle, installation, state, data, and deep links" correctly signals a multi-action app-management tool and enumerates the domains covered. However, "Manage" is a vague umbrella verb, and the description never differentiates this tool from siblings such as appium_session_management or appium_mobile_device_control, so the agent must inspect the action enum to know what it actually does.

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 when-to-use guidance, no alternatives, and no exclusions. All routing information (which action to pick, when confirmation is required, when to use this versus session tools) lives in the schema's action description, not in the tool description 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 only declare readOnlyHint=false and openWorldHint=false; the description adds real context beyond that, disclosing the 25-step cap, the returned payload shape, and the default 10s element wait for taps/types. It does not explain what happens when a step fails mid-batch or whether partial mutation persists, which matters for a non-read-only tool.

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

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

Three sentences, front-loaded with the core capability, then locator syntax, then timing behavior. No filler and nothing buried.

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

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

No output schema exists, yet the description states the return shape (per-step results plus screen summary), which covers the main gap. The step-variant semantics (e.g. what 'read' returns, 'until'/'timeoutSec' interaction) and failure behavior remain unspecified for a fairly complex nested 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 75% and the nested oneOf step variants carry no per-property descriptions, so the description compensates with genuinely additive detail: the locator prefix grammar (id=, desc=, text=, xpath=, uia=, pred=) appears nowhere in the schema. The wait-default and stopOnError/observeAfter defaults it mentions are already documented in the schema, so not every sentence adds meaning.

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 and resource: 'Run up to 25 steps (tap, type, wait, read, back, pause) in ONE call', plus what it returns ('per-step results plus a compact screen summary'). The batching scope makes it distinguishable from single-action siblings like appium_perform_actions or appium_find_element, though no sibling is named explicitly.

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

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

The 'in ONE call' framing implies this is for multi-step sequences rather than single interactions, but the description never states when to prefer it over appium_perform_actions or when a single-step tool is the better choice. Usage is inferable rather than stated.

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

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

Annotations carry no behavioral hints (readOnlyHint=false, openWorldHint=false), so the description itself must disclose side effects. It states that list returns all contexts and the current context, and that switch changes to a target context, which covers the basic effects. However, it does not disclose what happens on invalid context, whether the switch persists, or any session-level implications, leaving significant behavioral gaps.

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 wasted words. The first sentence states the tool's overall purpose, and the second precisely defines the two actions, front-loading the essential information immediately.

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 3 parameters and no output schema, the description covers the core functionality but omits details an agent might need, such as what the switch action returns, error behavior for invalid contexts, and the effect on the active session. It is adequate for a knowledgeable user but not fully complete for autonomous 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?

Schema description coverage is 100%, so the input schema already documents all three parameters. The description adds marginal value by explaining the distinct outcomes of list versus switch, but it does not enrich the context or sessionId parameters beyond the schema's existing descriptions, so the 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 names a specific verb and resource, 'Manage Appium contexts', and enumerates the two supported actions (list and switch) with distinct effects. It clearly differentiates this tool from the many sibling Appium tools by focusing solely on context management, which is unique among the listed 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 description implies that the tool is for managing Appium contexts but does not explicitly state when to use this tool versus alternatives or when not to use it. It provides no prerequisites or conditions beyond the actions themselves, so an agent must infer usage context from the tool name and 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?

Annotations only declare readOnlyHint and openWorldHint; the description adds real behavioral context by stating it never retries and never changes state, and by enumerating what evidence it collects and that causes come with confidence scores. The main omission is the cost/latency profile, since reading logcat can be slow and is on by default.

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 well-ordered sentence: purpose first, then the checks performed, then the outputs, then the read-only guarantee. Nothing is redundant, though the mid-sentence parenthetical list of screen conditions makes it slightly heavy to parse.

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, all-optional diagnostic tool with no output schema, the description adequately covers what the tool inspects and roughly what it returns (evidence, likely causes, next steps). It stops short of describing the shape of that evidence or how to act on confidence values, but the essentials for correct invocation are present.

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 every parameter is already documented, including the includeLogs default and the sessionId fallback to the active session. The description adds only indirect hints (it mentions logcat signals and screen/app state) and no new syntax or selection guidance, 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?

Names a specific verb-and-resource: it diagnoses a failure by checking session liveness, app state, screen state (dialog, keyboard, hidden/ambiguous/disabled target) and logcat crash/ANR/network signals, then returns evidence plus ranked causes and next steps. That is far more specific than the sibling tools (appium_screen_intel, appium_session_health, appium_observe), which each cover only one facet.

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 trigger is explicit and front-loaded: 'after a step fails'. An agent knows exactly when to reach for it. It does not, however, name how it relates to overlapping siblings such as appium_session_health or appium_screen_intel, so an agent cannot tell from this text whether diagnose subsumes them or should be paired with them.

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 goes beyond the sparse annotations by disclosing the exact gesture sequence (long press, drag, release) and default durations (600ms and 1200ms). It also explains that source and target can be an element UUID or coordinates, adding practical behavioral context beyond what annotations 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?

The description is compact and front-loaded, with the core action stated first, followed by the gesture mechanics and then representative use cases. Every sentence contributes useful information without unnecessary 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 tool with 9 parameters and no output schema, the description covers the essential behavioral contract: what gesture is performed, the timing defaults, and the two ways to specify source and target. It does not exhaustively explain every edge case, but it is sufficiently complete for an agent to select and 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 100%, so the baseline is 3. The description repeats default timings and the element/coordinate alternative that are already present in the parameter schemas, but it does not add significant new meaning beyond what the structured 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?

The description names a specific verb and resource ('Perform a drag-and-drop gesture from a source location to a target location') and details the gesture mechanics, making it clearly distinct from gesture-related siblings like appium_gesture and appium_perform_actions. It also clarifies the two acceptable input forms (element UUID or coordinates).

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 clear usage context with concrete examples ('Useful for reordering lists, moving items, drag-to-delete'), which helps an agent decide when to use this tool. However, it does not explicitly name alternative tools or state when not to use 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 provide no real behavioral cover beyond readOnlyHint=false, so the description carries the burden. It usefully reveals that get returns JSON settings and update merges a map into the session, but it does not describe update response behavior, side effects, or failure cases. 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 sentences with no filler: the first front-loads the tool's purpose and action modes, and the second scopes supported client types. 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 moderately simple settings tool, the description covers the main operational distinctions: reading vs. updating, merge semantics, and supported session types. Since there is no output schema, it could have specified what update returns, but the core usage 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 100%, so the schema already documents all parameters. The description adds some useful context by naming typical settings keys and explaining the get/update split, but it does not significantly compensate beyond the schema's own detailed parameter 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 uses a specific verb-resource pair ('Read or update Appium driver session settings') with concrete examples like idle timeouts and selector waits. It is clearly distinct from the sibling tools by targeting driver session settings, though it does not explicitly name or differentiate itself from a 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?

The description gives explicit action-level guidance: use action=get to read settings and action=update to merge a settings map. It also clarifies supported session types (embedded UiAutomator2/XCUITest and remote WebDriver clients), which helps an agent decide when this tool applies.

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 cover the safety profile (readOnlyHint, openWorldHint), so the description's job is supplementary. It does add real value: the return shape ('Returns driver attributes as JSON'), the elementResponseAttributes dependency on appium_driver_settings with shouldUseCompactResponses=false, and the caveat against natural-language selectors. It stops short of describing failure behavior when an element is not 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?

Front-loads the core purpose and the returned-UUID contract in the first two sentences, with preference ordering and cross-tool routing after. Dense and mostly waste-free, though the driver-settings aside could be trimmed.

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-format burden and does so ('driver attributes as JSON'). Combined with strategy guidance, the scroll alternative, and the vision fallback, an agent has everything needed to select and call this 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 100% and the strategy enum is thoroughly documented in the schema itself (per-platform guidance is already in the enum/param descriptions). The description's strategy preference ordering largely repeats the schema, so it adds direction but little new 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?

States a specific verb and resource ('Find an element by strategy and selector') and immediately clarifies the downstream contract: the returned element UUID is passed to interaction tools. It is cleanly distinguishable from the sibling appium_find_elements (plural).

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 the agent to alternatives: appium_gesture action=scroll_to_element for scrolling-until-found, and appium_ai action=find_element for the vision fallback. It also gives a concrete preference ordering (accessibility id > id > platform-native > xpath) with the reason xpath is last resort.

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, and the description goes well beyond them: it specifies the exact return payload, the empty-match contract, that elementId must be reused as elementUUID by interaction tools, and the shouldUseCompactResponses=false prerequisite for elementResponseAttributes drivers.

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 tight sentences, front-loaded with the core behavior and return shape, then interaction hand-off and configuration caveat. No filler or repetition.

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 compensates by describing the returned JSON structure and the empty-result case, plus how to configure compact responses. Nothing needed to call or consume the result 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%, with rich per-strategy guidance and an enum, so the schema carries the parameter burden and baseline is 3. The description adds only an output-side note about passing elementId as elementUUID, not new input 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?

States a specific verb and resource ('Find all elements matching a strategy and selector') and explicitly distinguishes itself from appium_find_element by match-count semantics. An agent can select it 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?

Names the alternative (appium_find_element) with the selecting condition ('when only one match is needed'), and the selector schema routes vision/natural-language lookups to appium_ai action=find_element. Explicit when-not guidance is present.

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 that the tool executes a scenario via MCP tools, observes interactions, and then produces test code, which is meaningful behavioral context. However, with sparse annotations it omits side-effect details, session or device prerequisites, and whether the generated code is returned inline or written elsewhere.

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, both information-dense: the first explains the workflow and output, and the second provides actionable locator-selection guidance. There is no filler or redundant repetition of 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 one-parameter tool with a documented schema, the description is mostly adequate: an agent can infer the expected input and output. The main gaps are missing prerequisites such as an active Appium session or device, and the expected granularity of the steps input.

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 fully documents the single steps parameter as the steps of the test, and the description only alludes to it via the word scenario. No additional formatting, granularity, or example guidance is provided, so this stays at the schema-coverage baseline.

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 first sentence states a specific outcome: return a workflow to execute a scenario and then generate test code from observed interactions. The second sentence differentiates the tool from appium_find_element and generate_locators, making the purpose largely unambiguous.

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

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

The description gives explicit routing guidance: prefer appium_find_element for targeted element location and reserve generate_locators for broad inspection. It does not enumerate all exclusion cases or alternative tools, but the context is clear enough for an agent to decide when to use 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?

Beyond the minimal annotations, the description discloses meaningful behavioral caveats: Android emulator reset is unsupported, mocked locations may persist until GPS cache refresh on Android real devices, and altitude is Android-only. These details help an agent anticipate platform-specific outcomes. The readOnlyHint=false annotation is consistent with the mutating set/reset 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?

The description is compact and front-loaded, starting with the core function and platform scope before detailing action modes and edge cases. Every sentence contributes operational information, and there is no filler or redundant restatement.

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

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

The description fully covers action selection, platform constraints, required parameters, and important caveats. There is no output schema, and the description does not specify the exact return shape of action=get, but the invocation path is otherwise complete and unambiguous.

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 explaining action semantics and platform dependencies, such as action=set requiring latitude/longitude, altitude being Android-only, and reset having an Android emulator limitation. This supplements the schema rather than merely repeating it.

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 'Get, set, or reset the device geolocation (GPS coordinates)', providing specific verbs and the resource being operated on. It clearly distinguishes this tool from sibling Appium tools by naming the exact geolocation capability and supported platforms.

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 action-based guidance: use action=get to read, action=set with latitude/longitude to simulate, and action=reset to restore defaults. It also notes that reset is unsupported on Android emulators and directs users to action=set instead. It does not mention alternative sibling tools, but it clearly scopes its own usage 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 declare readOnlyHint=false and openWorldHint=false, so the safety profile is clear. The description adds action-level intent such as browse versus dismiss versus pull-to-refresh, but it does not describe side effects, waits, or failure behavior beyond what the schema already covers.

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 three tight sentences, front-loaded with the core action and followed by action selection and sibling routing guidance. It contains no filler and does not redundantly restate the long 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 17-parameter gesture tool, the description provides the high-level action model and sibling routing while the schema carries the detailed mechanics. It is nearly complete, though a complex eight-action tool could briefly mention session or element-precedence behavior at a high level.

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 every parameter is documented in detail, so the description does not need to repeat coordinate, duration, or locator mechanics. It does add useful action-selection semantics that the schema does not fully capture, especially scroll versus swipe intent.

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, then enumerates the supported touch actions. It also distinguishes this tool from appium_drag_and_drop and appium_perform_actions, so an agent can route correctly 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 explicitly explains when to use scroll versus swipe by intent and names the two sibling alternatives for drag-and-drop and custom multi-touch. The pull-to-refresh speed hint further reduces 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?

The read-only behavior is already covered by annotations, so the description doesn't need to restate that. It adds useful context by specifying that the tool returns a UUID intended for follow-up interactions. It does not mention edge cases like what happens when no element is focused, but that is a minor omission for such a simple read-only tool.

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

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

The description is two short, efficient components: the purpose first, then the priority usage note. There is no filler, and the key information 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 one-parameter, read-only tool with safety annotations, the description is nearly complete: it states what is returned (UUID) and why it matters. The only real gap is the lack of guidance on the no-focused-element case, especially given the absence of an output 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%: the only parameter, sessionId, is already documented as defaulting to the active session. The description adds no parameter-level detail, so the schema carries the semantic load and the 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 uses a specific verb and resource ('Get the currently active/focused element') and states a concrete output ('return its UUID for follow-up interactions'). This clearly distinguishes it from siblings like appium_find_element, which search for elements rather than report the current focus.

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 context: 'Use this first when you need to find what element currently has focus.' This is clear and actionable, but it does not name alternatives or state when not to use it, so it stops 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?

The annotations already declare readOnlyHint=true, and the description is consistent with that non-destructive getter. The description adds no further behavioral detail beyond the annotation, such as what happens if the attribute does not exist or the exact return format.

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

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

Two short sentences with no filler. The core action is front-loaded, followed by the practical use cases, making it easy to parse quickly.

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 3-parameter tool with full schema coverage, the description is largely sufficient for selection and invocation. The main omission is the exact return type or null behavior for missing attributes, but that is minor given the tool name and examples.

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 100% schema description coverage, the baseline is 3, but the description adds meaningful semantic grouping by separating state attributes from property attributes. This helps the agent choose appropriate values for the attribute parameter beyond what the schema lists.

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 ('Get the value of an element attribute') and concrete use examples, so an agent can tell what the tool does. It does not explicitly differentiate it from the overlapping sibling appium_get_text, which can also retrieve text or value attributes.

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 explicitly says 'Use this to check element state... or read properties', giving clear contexts for when the tool is appropriate. However, it does not mention when not to use it or when to prefer a sibling tool, so it stops 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?

The description usefully explains that saveToFile=true returns a server-local path/bytes rather than XML, which explains why readOnlyHint=false despite this being a read-style operation (it writes a file server-side). However, 'enables selector/pattern summaries' is ambiguous — it does not say whether selector/pattern are ignored or rejected without saveToFile=true, and there is no note on output size or cost of full-mode XML.

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

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

Two short sentences with the core action front-loaded and no filler. The second sentence is dense but slightly cryptic ('enables selector/pattern summaries'), costing a bit of clarity for its 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?

For a five-parameter tool with zero required params and no output schema, the description is thin: it omits any indication of what the XML/compact output looks like, how large it can get, and how it relates to the many competing observation tools. The saveToFile behavior is well covered, but the default full-mode path is not.

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 meaning beyond the schema: it clarifies the returned path is server-local (not client-fetchable) and ties saveToFile to the selector/pattern behavior. The linkage between saveToFile and the filtering parameters is the kind of cross-parameter interaction the schema alone does not convey.

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: 'Get current-screen XML', which is unambiguous about what is returned. It does not differentiate itself from nearby siblings such as appium_screenshot, appium_screen_intel, or appium_find_element, so an agent must infer when raw page source beats those options.

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

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

There is no when-to-use or when-not-to-use guidance in the description; it never mentions the sibling tools that overlap (screenshot, screen_intel, find_element). The only usage hint ('use when you only need to act') lives in the mode enum in the schema, not in the 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 aligns with readOnlyHint=true and does not contradict the annotations, but it adds no behavioral detail beyond them. There is no mention of return format, stale-element behavior, or side effects, so the description contributes little transparency that the annotation doesn't already supply.

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 or redundancy. It is appropriately compact for a simple getter tool, though it sacrifices explanatory richness 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?

For a two-parameter read-only getter with a well-documented schema and readOnly annotation, the tool is minimally callable. However, there is no output schema, and the description could usefully state that the return value is the element's text content; it also fails to route agents away from nearby siblings.

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?

Both parameters are already described in the JSON schema: sessionId defaults to the active session and elementUUID comes from appium_find_element. With 100% schema coverage, the description adds no extra parameter meaning, so the baseline score 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?

The description states a specific operation ('Get text') and target ('from an element'), making the core purpose immediately clear. However, it doesn't contrast with related siblings such as appium_get_element_attribute or clarify whether 'text' means visible text vs. an attribute value.

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 like appium_get_element_attribute or appium_get_active_element. The only implied trigger is needing text from an element, but no prerequisites, exclusions, or contextual cues 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?

No contradiction with annotations: readOnlyHint=true matches the read-only 'Get' wording. The description adds useful context beyond the annotation by specifying the result is the device screen dimensions in pixels rather than element-level or abstract coordinates.

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

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

Two short sentences with no redundancy: the first states the return value and unit, the second states the practical use case. 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?

The tool is simple: one optional parameter, read-only, and the return semantics are clear from 'width and height in pixels.' The description plus schema fully equip an agent to decide to call it 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 description coverage is 100% and the only parameter, sessionId, is already documented as 'Session ID; defaults to the active session.' The description adds nothing needed about parameters, so the schema carries the 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?

The description names a specific verb and resource: 'Get the width and height of the device screen in pixels.' This clearly distinguishes the tool from sibling getters like appium_get_text, appium_get_element_attribute, appium_get_page_source, and appium_get_active_element.

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

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

It gives a concrete intended use: 'calculating coordinates for swipes, taps, and scrolls,' which tells an agent when to call it. It does not explicitly name exclusions or alternative tools, but for a simple screen-size query the context is 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 only declare readOnlyHint=true and openWorldHint=false, so the description carries real weight here and does so well: it explains match-count semantics (1 = unique), the 0-100 stability score, the three warning classes (value-dependent ids, positional xpath, hidden target), and that results are ordered with the recommended locator first. The staleness caveat about re-verifying after navigation is exactly the kind of behavioral context 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?

Two sentences, purpose first and caveat last, with no filler; each clause (match count, stability score, warnings, ordering) conveys a distinct fact. The sentences are densely packed with parenthetical clauses, which costs a little readability but not substance.

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 must explain the return value and largely does: a ranked list of locator candidates with match counts, stability scores and warnings. The remaining gap is that it never says which locator strategies are emitted (id, accessibility id, xpath, etc.), which an agent needs to know to use the candidates.

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 88%, so the schema already documents id, text, input, limit, clickable, sessionId, verbosity and includeHidden in detail. The description adds only indirect meaning, e.g. the 'hidden target' warning implicitly ties to includeHidden and 'by description' maps loosely to text/id. Baseline 3 is appropriate since 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?

States a specific verb and resource ('find target element(s) by description') plus the distinctive output ('validated locator candidates'), which separates it from plain find tools like appium_find_element/appium_find_elements and from generate_locators. It never names a sibling explicitly, so the differentiation is inferred rather than stated.

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

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

Usage is implied rather than prescribed: the tool is for discovering stable locators before authoring a test, and the closing note gives a concrete rule ('counts come from the current screen, so re-verify after navigation'). There is no explicit when-not guidance and no named alternative for cases where the agent already knows the locator or just wants to interact with an element.

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 readOnlyHint=false, so the description's confirmation of a set/write mode adds modest value. It does contribute platform scope, plain-text semantics, and the behavior that action=get returns current text. However, it does not disclose side effects such as replacing the existing clipboard contents or any platform-specific failure behavior; these would be useful but are not severe omissions.

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 operation is front-loaded, followed by the mode-specific behavior and the prerequisite condition for set. 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-action clipboard tool, the description plus the input schema is sufficient to invoke it correctly: action is required and enum-limited, content is required when setting, and sessionId defaults to the active session. The return for get is described as current text, and no output schema exists. Minor caveats such as clipboard persistence or platform restrictions are not covered, but the tool is simple enough that the current description feels 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 all three parameters are already documented. The description adds a little extra meaning by linking action=get to returning text and action=set to requiring content, but this mostly restates the schema's enum descriptions rather than providing substantial new semantic information. 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 precise verb+resource pair: 'Read or set the device clipboard as plain text.' It also narrows the scope by naming the supported platforms (Android UiAutomator2 / iOS XCUITest) and enumerating the two modes via action=get and action=set, which clearly distinguishes it from sibling tools that target elements, keyboards, or sessions.

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

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

The description gives explicit mode-level guidance: 'action=get returns current text; action=set requires content.' This tells the agent exactly when each action branch is appropriate and which parameter is needed. It does not name alternative sibling tools for exclusion, but there is no obvious clipboard-specific sibling among the listed tools, so the guidance is sufficiently 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 declare readOnlyHint=false, so the agent knows this mutates state. The description adds no further behavioral context beyond what the schema already provides (platform-specific actions). It does not disclose side effects like disrupting the app under test or requiring an active session. Since annotations cover the mutation aspect and the schema covers platform limitations, a 3 is appropriate – the description adds minimal but non-contradictory context.

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 that immediately states the tool's purpose and points to the key parameter. It is concise, avoids repetition, and contains 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 tool with three parameters fully described in the schema and no output schema, the description is adequate. It explains what the tool does and directs the agent to the action parameter. It does not mention preconditions like device availability or potential interference with the test, but these are not strictly required for correct invocation. The description is complete enough for an agent to 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 description coverage is 100%, so all parameters are documented in the schema. The description only says 'Use the action parameter to choose what to do,' which adds no additional meaning beyond the schema's detailed enum and per-parameter descriptions. Baseline 3 is correct when the schema fully documents parameters.

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 resource (device behavior) and lists specific actions: lock/unlock the screen, shake, open notifications. This is distinct from sibling tools like appium_gesture (screen gestures) or appium_orientation (screen rotation), making the purpose immediately 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?

The description implies usage: if you need to perform these device-level actions, use this tool. However, it does not mention alternatives or when not to use it, such as 'use appium_gesture for screen-level interactions' or platform-specific exclusions (though the schema does note iOS-only for shake and Android-only for open_notifications). No explicit when/when-not guidance 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds cross-platform applicability and that all three data points come back in one call, but says nothing about session fallback behavior or whether failures raise or return partial data. With annotations present, a 3 fits.

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 sentences, front-loaded with what the tool retrieves and then how to select it. No filler; the platform note earns its place as scoping information.

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

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

There is no output schema, yet the description does not characterize return shape beyond the action labels, and the schema's own descriptions carry most of that burden. For a simple read-only tool this is close to adequate, but it does not fully cover what an agent gets back.

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 itself spells out the action enum, the moment.js format string, the sessionId default, and the verbosity modes. The description only restates that 'action' selects the data, adding nothing beyond structured fields, 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?

The description names a concrete verb plus three specific resources (device info, battery status, device time), so an agent knows exactly what the tool returns without opening the schema. It is clear enough to distinguish from siblings like appium_orientation or appium_geolocation, though it never explicitly says so.

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 tells the agent to use the 'action' parameter to pick which datum to fetch and that it works on iOS and Android, which is useful routing context. It gives no explicit when-to-use vs alternatives guidance (e.g., vs appium_session_health for status, or appium_observe for broader state).

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

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

Annotations already declare readOnlyHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds that pull returns contentBase64 (useful return-shape context), but omits the two-step CONFIRMATION REQUIRED flow documented only in the schema and says nothing about overwriting existing device files or permission 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?

Two short sentences, zero filler, and the primary capability is front-loaded before the per-action data requirements.

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, noting the contentBase64 return is valuable, but the definition stays silent on the confirmation-token workflow and on overwrite/destructive semantics for push — meaningful gaps for a file-write tool with five parameters.

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 every parameter is already documented, including action, remotePath formats, and the confirmToken requirement. The description's 'action=push uses payloadBase64' restates exactly what the schema says, adding no new syntax or format detail, 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 ('Push or pull') and resource ('a file') scoped to Appium mobile extensions, and names both modes. No sibling tool performs file transfer, so differentiation is de facto clear, though it never explicitly says it is the only/right tool for this job.

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 push/pull split implies when each mode applies (upload vs. download), but there is no explicit 'use this when' guidance, no prerequisites, and no mention of the confirmation handshake that governs push.

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 indicate readOnlyHint=false, so the tool is expected to mutate state. The description confirms the hide action is mutating and the is_shown action is a query, but does not add deeper behavioral details such as side effects when the keyboard is already hidden, platform-specific quirks, or error conditions. It adds the platform scope (Android/iOS), which is useful context beyond 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 concise sentences with the core purpose front-loaded, followed by the action mappings. Every word earns its place; there is no fluff or redundancy, making it efficient and easily scannable.

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 three parameters and no output schema, the description covers the actions but fails to specify the return value for is_shown (expected boolean). It also does not mention error handling or platform-specific behaviors. While the core functionality is clear, the missing return-type detail leaves a gap for an agent relying on the description alone.

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 description duplicates the parameter information already present in the schema (e.g., keys are only for hide, action enum). It adds no new semantic value beyond what the schema provides, so a baseline score 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?

The description states a clear verb-resource pairing: hide the software keyboard or check its visibility, scoped to Android/iOS. It names the two specific actions (hide, is_shown) and maps them to Appium commands, making the purpose unambiguous and distinct from sibling tools like appium_mobile_press_key.

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 states what the tool does and the two action variants, but does not explicitly say when to use it versus alternatives or when not to use it. The context is implied (keyboard control), but no exclusions or sibling routing is provided, leaving the agent to infer appropriateness.

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 non-read-only, closed-world tool, and the description correctly reflects that mixed read/write nature plus the platform boundary (iOS reset is Simulator-only, reset is iOS-only). It does not disclose prerequisites such as AppleSimulatorUtils for iOS, permission/entitlement requirements, or what state is lost on reset, so it adds only moderate context beyond 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?

A single front-loaded sentence pairs the action scope with the platform scope, and the trailing pointer to action-specific parameters is short. The only weakness is that 'See action-specific parameters' spends words without conveying 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 an 11-parameter, nested-object tool with no output schema, the description conveys the operation surface but leaves platform prerequisites and the relationship between action and required parameters to the schema. It is adequate given the rich schema, but not self-sufficient for an agent choosing between the three actions.

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 every parameter is already documented in the schema, including action, target, service, access, and permissionChangeAction. The description adds nothing parameter-specific beyond pointing at the schema, 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 uses specific verbs and a named resource: read/update Android app permissions, read/update iOS Simulator privacy services, and reset iOS privacy prompts. It clearly separates the two platforms, which no sibling tool covers, though it does not explicitly name a sibling it is distinct from.

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?

Platform scoping (Android vs iOS Simulator) implies when each path applies, but there is no explicit when-to-use guidance and no routing away from adjacent tools such as appium_driver_settings or appium_app_lifecycle. 'See action-specific parameters' defers the decision to the schema rather than explaining 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 signal a non-read-only operation, so the description only needs to add behavioral context. It adds platform-specific key behavior and implies navigation side effects via key names, but it does not explicitly state effects like leaving the current screen (HOME/APP_SWITCH) or changing volume, nor does it mention long-press 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?

A single sentence delivers the core action and platform scope with no filler or repetition. It is front-loaded and 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?

The input schema fully documents all four parameters, including platform restrictions and keyCode precedence, so the brief description plus the schema gives an agent what it needs for a simple key press. The main missing piece is relationship guidance to sibling input tools, 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%, so the baseline is 3 and the schema already documents key, keyCode precedence, sessionId, and isLongPress. The description only echoes a subset of key-to-platform mappings and adds no new meaning 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 opens with the specific action 'Press' and identifies the exact resources: navigation keys (BACK, HOME, APP_SWITCH) on Android and physical buttons on iOS/tvOS. This clearly distinguishes the tool from sibling input tools like appium_mobile_keyboard and appium_gesture without needing to open 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?

There is no guidance about when to choose this tool over alternatives or when not to use it. The only context is platform coverage ('on Android' vs 'on iOS/tvOS'), but the description never names a sibling like appium_mobile_keyboard or appium_perform_actions or gives a selection condition.

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 safety and scope are covered. The description adds cost/relative-expense context and the contents of each output line, which is genuinely useful, but says nothing about pagination/truncation behavior at limit=300 or about what 'diff' compares against beyond the schema's wording.

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, both front-loaded with the most decision-relevant facts: what the output looks like, its relative cost, and the one usage rule. No filler.

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

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

With no output schema, the description takes on the job of describing return contents and does so via the field list (class, id, desc, text, flags, center). Defaults for diff, limit, and includeText are left to the schema, which is reasonable given full 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 coverage is 100%, so the baseline is 3; the description earns an extra point by giving the diff parameter situational meaning ('after an action') that the schema's 'since the last observe' does not convey.

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

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

The description names the resource (current screen) and the exact shape of the result (one line per element with class, id, desc, text, flags, center), which clearly distinguishes it from bulkier siblings like get_page_source. It lacks an explicit verb ('return'/'observe'), presenting itself as a noun phrase, but an agent can still tell precisely what it gets.

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 names two alternatives (page source, generate_locators) and frames this as the cheaper option, and it gives a concrete trigger for the diff parameter: 'Use diff=true after an action.' It stops short of stating when NOT to use it, such as when full hierarchy or attributes are required.

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; the description adds that the tool can set orientation to LANDSCAPE or PORTRAIT. However, it does not mention side effects, persistence, or what the get action returns, leaving some behavioral detail undisclosed.

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, well-structured sentence that front-loads the core purpose and then lists supported actions and values. There is no filler or redundant 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?

The schema covers parameters and required fields, and the description conveys the get/set semantics. However, since there is no output schema, the description does not explain what the get action returns, which is a small but relevant completeness 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 schema fully documents all three parameters and enums. The description mostly restates what the schema already provides (action=get/set, LANDSCAPE/PORTRAIT) without adding new semantic 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?

The description clearly states the verb-resource pair: 'Get or set the device/screen orientation.' It is specific enough to identify the tool's purpose, though it does not explicitly contrast it with sibling tools, so it misses the top score.

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 usage is implied: use this tool when you need to read or change the device orientation. It does not explicitly state when to prefer this over related siblings like appium_get_window_size or appium_context, nor 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 only mark readOnlyHint=false and openWorldHint=false, so the description must carry the interaction model — and it does, noting that multiple pointer sources run in parallel and are synchronized tick-by-tick, and that it is raw/low-level compared to the platform-normalizing sibling. It stops short of covering failure behavior (invalid action chains, element-level vs viewport coordinates, timeouts), which matters for a raw-action tool.

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

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

Three sentences, each earning its place: capability, concrete use cases, then the routing rule to the alternative. Nothing is repeated from the schema and the highest-value 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?

For a complex, highly-nested tool with no output schema, the description plus the fully documented schema give an agent what it needs to construct a valid call and choose the right tool. The remaining gap is expected failure/error semantics for malformed action chains, which is secondary given the schema quality.

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 nested action structure (pointerType, origin, duration, button) is fully documented in the schema, so the baseline is 3. The description adds only the conceptual framing that individual sources correspond to fingers in multi-touch, not syntax or format detail 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?

States a specific verb and resource — 'Execute raw W3C Actions API sequences' — and immediately scopes it against the sibling appium_gesture. An agent can distinguish this from the sibling without opening either schema, because the description names which gestures belong here (rotate, three-finger swipe, edge swipes) and which do not.

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 both directions explicitly: use this for custom multi-finger gestures, complex timing, or precise per-touch-point control; prefer appium_gesture for standard gestures (tap, scroll, swipe, pinch). The alternative and the condition selecting it are named, plus a concrete reason (automatic platform handling).

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?

Description discloses substantial behavior beyond annotations: omitting provisioningProfileUuid lists profiles, wildcard profiles use a concrete WDA bundle ID, downloads/unsigned IPA are cached per version while signing always reruns, and the tool hands off to appium_session_management. It also states prerequisites and the need to ask the user, which the readOnlyHint=false annotation alone does not 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?

Dense but efficient: purpose, user-interaction flow, cache behavior, handoff, and requirements each earn their place. The most important operational detail (omit UUID to list profiles) appears immediately after the purpose.

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, mutating tool with no output schema, the description covers prerequisites, two modes of operation, the exact next step (capabilitiesHint to appium_session_management), and cache semantics. However, it leaves the concrete shape of the returned profile list unspecified beyond 'list of available profiles' and 'recommendedForWda', so an agent lacks full return-value transparency.

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 already documents all three parameters (100% coverage), so baseline is 3. The description adds workflow-level meaning: the omission semantics of provisioningProfileUuid, the recommendedForWda highlighting, the cache/forceRebuild interaction ('signing always reruns'), and wildcard-profile behavior. This is meaningful but not exhaustive enough to warrant 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: 'Prepare signed WDA for a real iOS device.' This clearly distinguishes from the sibling prepare_ios_simulator by targeting real devices, and the rest of the description narrows the exact deliverable (signed WDA).

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 clear context: real iOS device, requires macOS, Xcode 16+, paired developer-mode device, and a two-step flow depending on provisioningProfileUuid. It does not explicitly name an alternative like prepare_ios_simulator or state when not to use this tool, so it falls short of the 5-level 'explicit when-not/alternatives' 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds that output is a summarisation rather than raw source, that it includes below-the-fold content beyond the visible viewport, and that it returns suggested next actions. It does not discuss size/latency characteristics or how verbosity affects the payload (the schema handles the parameter, not the 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?

Two sentences, zero filler, with the primary capability front-loaded and the competitive positioning (replaces page source + finds) as the closing justification. Every clause corresponds to a concrete output element.

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

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

With no output schema and a non-trivial aggregation tool, the description usefully enumerates the shape of the result and mentions below-the-fold and suggested actions, which an agent could not otherwise infer. Minor gap: it does not clarify that the call is viewport-scoped versus full-tree, nor how verbosity changes the summary depth.

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 all three optional parameters documented, including the snapshot linkage to appium_ui_diff and the verbosity default, so the schema carries parameter meaning. The description adds no additional syntax, defaults, or interaction guidance for these parameters, placing it at the baseline.

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

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

Names a specific verb pair (classify, summarise) against a precise resource (the current screen) and enumerates exactly what is produced: type, inputs, buttons, navigation, keyboard/dialog state, below-the-fold content, suggested actions. It also positions itself against siblings by stating it replaces page source plus several finds, which maps to appium_get_page_source and appium_find_element(s).

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?

"One call replaces page source + several finds" gives clear context for preferring this tool over the low-level inspection siblings. It stops short of explicit exclusions or sequencing advice (e.g., when to prefer appium_locator_intel or appium_observe instead), so it is clear guidance without full when-not coverage.

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 readOnlyHint=false and openWorldHint=false, which is minimal context. The description adds that stop produces an MP4 file, but omits where that file lands, whether the path is returned, how forceRestart interacts with an in-flight recording, and that the recorder is stateful per session.

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

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

Two short sentences with the core capability front-loaded and zero filler. Nothing is repeated or padded.

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

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

For a stateful 13-parameter recorder with no output schema and thin annotations, the agent still lacks the outcome of the call — where the MP4 is saved or whether a path is returned — and any note that recording must be stopped explicitly. The description is far too thin for this tool's complexity.

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 documents action semantics, platform scoping, defaults, and the timeLimit caveat. The description's 'action=start/stop' restates what the schema already says, so baseline 3 applies with no added meaning.

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 ('Start or stop screen recording') and clarifies both action values, so an agent knows exactly what the tool does. It never contrasts itself with the nearby appium_screenshot sibling or other capture tools, so differentiation is left implicit.

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 start/stop pairing implies a workflow (begin capture, then terminate to persist), but there is no explicit guidance on when to choose recording over screenshot, when a session must already exist, or whether recording should be stopped before session teardown.

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 the core behavior: capturing a screenshot and saving it as PNG. It does not contradict the annotations, but with readOnlyHint false and openWorldHint false, the annotations add little context, and the description does not mention output paths, return semantics, or limitations such as element visibility.

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 concise sentence that front-loads the main action and then introduces the optional element capture. Every word contributes to understanding, with no filler or repetition.

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 screenshot tool with fully documented parameters, the description plus schema is largely sufficient. It lacks an explicit statement of the return value, such as the saved file path, but the returnRawBase64 parameter description partially covers that expectation.

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 all parameters are already well documented. The description mostly restates the elementUUID behavior found in the schema without adding significant new 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?

The description uses a specific verb and resource: 'Take a screenshot and save as PNG.' It also distinguishes the element-capture mode from full-screen capture, making the tool's purpose clear and distinct from siblings like appium_screen_recording or appium_get_page_source.

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 purpose implies the tool should be used for still visual capture, and the optional elementUUID note adds a usage mode. However, it does not explicitly mention alternatives, such as screen recording or page source, or state when one should be preferred over the other.

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 readOnlyHint=false and openWorldHint=false, so the mutating nature is already signalled; the description nonetheless adds real value with a rate bound (2 attempts per 10 minutes), scope guarantees (never touches other sessions, never resets app data), and the post-replacement verify step. It does not describe the shape of the returned signals or what the response looks like when recovery is attempted and fails.

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, front-loaded with the diagnostic scope before the recovery caveats, and essentially no filler. The second sentence is dense and runs long with stacked caveats, which slightly hurts scanability.

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-required-parameter diagnostic with no output schema, it covers what is checked, what is returned (failure kind plus signals plus a replacement verdict), and the exact guardrails on the one mutating path. Remaining gap is the response shape on a report-only call, which the description only summarizes.

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 still adds meaning for recover by narrowing it to specific failure kinds and by disclosing the retry ceiling, which the schema property text does not contain. It says nothing extra about detail or appId, and the default-to-active-session behavior it mentions is already 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 verb (Diagnose) and resource (a session), then enumerates exactly what is inspected: device state via adb, Appium server reachability, session liveness, app state/foreground, ANR dialog. That is far more specific than a title restatement, though it never names how it differs from siblings like appium_diagnose or appium_session_management.

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 clear condition for the mutating path: recover=true applies only to a recoverable failure (dead session or driver), and it states exclusions — cloud and attached sessions are not replaced. What's missing is routing guidance against the obvious alternatives (appium_diagnose, appium_session_management) for the non-recovery case.

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

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

The description adds meaningful lifecycle distinctions beyond the annotations, especially that attach does not take ownership and detach removes a session from MCP without deleting the real remote session. This complements destructiveHint=true by clarifying which actions actually destroy resources.

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 general purpose and then compactly maps each action to its effect. Every clause contributes to selecting the correct action, with no redundant wording.

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 six-parameter, destructive, multi-action session tool, the description provides adequate high-level action semantics, while the very rich schema carries the detailed create/attach/capability behavior. The top-level description itself does not surface the local-versus-remote create nuance, but that is well covered in structured schema descriptions.

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 meanings are already documented in detail, including remote/local create behavior and confirmation requirements. The description only restates the action values and does not add parameter-level meaning 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 identifies session lifecycle management and enumerates all six actions, so the resource and operations are unambiguous. It does not explicitly contrast itself with sibling tools, keeping it below 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?

It gives direct action-selection guidance: create to start, attach for existing sessions, detach to forget without deleting, delete to stop, list to inspect, and select to activate. It lacks explicit when-not-use conditions or alternatives outside this tool, but the internal action routing 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 indicate readOnlyHint=false, so the mutation behavior is known. The description adds no further behavioral context such as whether existing text is replaced, whether the element must be editable, or how w3cActions changes focus 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 a single, front-loaded sentence with no filler or redundant wording. It is appropriately concise for the simple operation it names.

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

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

The schema covers all parameters and annotations cover the mutation profile, but the description alone is thin for a tool with two distinct input modes (elementUUID vs w3cActions). Missing usage guidance and behavioral details prevent it from being fully self-sufficient.

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 parameters are fully documented in the schema. The description itself adds no parameter-level meaning, but the baseline of 3 applies because the schema carries the 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?

The description uses a specific verb and resource: 'Enter text into an element'. It clearly identifies the operation and target, and is distinguishable from sibling read tools like appium_get_text, though it does not explicitly name or contrast 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?

There is no guidance on when to use this tool versus alternatives such as appium_mobile_keyboard, appium_mobile_press_key, or appium_perform_actions. No exclusions, prerequisites, or selection criteria 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real context beyond that: it operates against the live/current screen state rather than a cached snapshot, and it defines the interpretation thresholds for the returned counts. It says nothing about cost, timing, or whether the screen is re-queried per locator.

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, zero filler, with the action front-loaded and the interpretation rule immediately after. Nothing redundant or out of 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?

For a two-parameter read-only tool with no output schema, the description conveys the essential shape of the result (a count per locator) and how to read it. The only gap is that it does not state the literal return structure or whether mismatched locators are reported together, but that is a minor omission here.

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%, including the note that locators use the same grammar as wait_for and that sessionId defaults to the active session, so the schema already carries the parameter meaning. The description adds only that counts are produced per locator, without elaborating on the array or the session override. Baseline 3 applies.

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

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

The description opens with a specific verb and resource: "Count matches for each locator on the live screen." That clearly separates it from the element-returning siblings (appium_find_element, appium_find_elements) and from appium_wait_for. It stops short of naming any sibling explicitly, so it lands at a clear-but-undifferentiated 4.

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 the decision rule for acting on the result: only a count of exactly 1 is safe for test code, >1 is ambiguous, 0 is absent. That tells the agent the situation this tool is for (validating a locator before committing it to a test). It does not mention when to skip this tool in favor of appium_wait_for or appium_locator_intel, so no explicit alternative routing.

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 safety is covered. The description adds that the tool polls, which is useful behavioral context. However, it omits critical wait semantics: polling interval, what happens on timeout (throw vs. return null/false), and whether the matched element is returned — none of which is recoverable from an output schema, since none exists.

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

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

Two short sentences, zero filler, with the core action stated first and the routing guidance second. Nothing could be trimmed without losing information.

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

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

With four fully documented params and no output schema, the definition is close to sufficient, but a wait tool's most important contract — timeout behavior and what is returned on success versus failure — is left entirely unstated. An agent cannot tell whether it must follow this with a find call or whether the element comes back directly.

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 locator syntax, the until enum, sessionId defaulting, and the 1-120s timeout range. The description only echoes the present/gone duality; it adds no additional 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 (poll/wait) and resource (a locator) plus the two conditions it supports (present or gone). It also implicitly distinguishes itself from appium_find_element by naming 'retrying find_element' as the thing it replaces.

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 usage rule: use this instead of retrying find_element after navigation. That names both the context and the alternative. It stops short of stating when NOT to use it (e.g., when you need the element handle itself, which presumably requires appium_find_element).

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description earns credit for disclosing the driver-dependent default filtering (controls for UiAutomator2/XCUITest/Web, all elements except hierarchy for other native drivers), which is real behavioral context not derivable from structured fields. It stops short of explaining what a 'locator candidate' actually is, whether results are ranked, or why hierarchy is excluded.

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 and scope, followed by the defaults. Nothing is wasted, though terms like 'controls' and 'hierarchy' are used without unpacking, which leaves the second sentence denser than it needs to be.

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

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

There is no output schema, so the description carries the burden of explaining the return value, and it does not: it never says what a candidate looks like (XPath, accessibility ID, UiSelector), how many are returned by default, or whether they are ordered. For a read-only, zero-required-param tool the risk is low, but the deliverable is underspecified.

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 exceeds that by defining what the 'default driver-specific filter' referenced in the query parameter actually resolves to per driver, which the schema leaves opaque. It adds no new detail on limit, sessionId, or xpathAttributes, but those 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 gives a specific verb and resource: 'Generate current-page locator candidates for inspection.' An agent immediately knows this produces candidate selectors for the currently loaded screen. It does not, however, distinguish itself from nearby siblings such as appium_locator_intel, appium_verify_locator, or appium_find_elements, so the differentiation job is left undone.

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?

'For inspection' implies the exploratory/debugging use case, but there is no explicit when-to-use statement, no when-not-to-use exclusion, and no pointer to alternatives like appium_verify_locator (to validate a chosen locator) or appium_find_element (to act on one). The usage is inferable but not 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 only mark this as not read-only, so the description carries the burden. It adds valuable behavioral context: WDA is cached, launched on a free per-simulator port, and can be skipped via an environment variable pointing to an already-extracted app. It doesn't describe failure modes or cleanup, but the main side effects are visible.

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 carry all necessary information, with the core action front-loaded and optional usage details following. It is appropriately concise, though the second and third sentences are dense and mix integration guidance with environment configuration.

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 explains the full setup flow: boot, WDA download/cache/launch, reuse via capabilities, and the skip-download path via environment variable. It implies the returned WDA URL without explicitly stating it, leaving a minor gap for an agent that needs to rely solely on this text.

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 references skipWda and the environment variable override, which supplements the schema slightly, but it does not add significant new meaning to the parameters beyond what the property descriptions already provide.

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+resource: boot an iOS/tvOS simulator, download/cache WebDriverAgent, and launch it on a per-simulator port. This clearly distinguishes it from the sibling appium_prepare_ios_real_device by targeting simulators and explicitly mentions Apple TV support.

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 concrete usage direction: pass capabilitiesHint (appium:webDriverAgentUrl) to appium_session_management to reuse WDA, and use skipWda=true when only booting is needed. It stops short of explicitly stating when not to use this tool or comparing it to the real-device sibling, so it isn't a perfect 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 provide little signal (both hints false), so the description carries the behavioral burden. It discloses interactive behavior: asking the user, auto-selecting one device, or requesting a choice among multiple. It also explains what to do in the remote case, giving the agent a clear behavioral contract, though it does not address no-device or failure scenarios.

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 with the core purpose, then proceeds through decision branches and exceptions. It uses semicolons and colons to pack workflow into three sentences with minimal waste. A bulleted structure might improve scannability, but 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?

Given the simple parameter surface and lack of an output schema, the description covers purpose, decision rules, the remote exception, and next steps for iOS simulators. It is missing a real-iOS device route and any behavior for zero devices found, but the overall flow is clear enough for an agent to invoke the tool correctly in common cases.

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 each parameter already has a meaningful description. The tool description adds only slight reinforcement, such as 'ask the user to choose, then pass deviceUdid,' which is already implied by the schema. There is no substantial semantic value 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?

The description opens with a specific verb and resource: 'Discover/select a LOCAL device.' It clearly delineates local versus remote use, which distinguishes it from sibling Appium session/device tools. The phrase 'Skip for REMOTE servers' further separates this tool's scope from session-creation 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?

The description gives explicit decision guidance: ask for platform if unknown, auto-select when one device, ask the user when multiple, and skip for remote servers by passing capabilities to session creation. However, it only names prepare_ios_simulator for iOS simulators and omits the real-iOS preparation path, leaving a sibling-adjacent gap.

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