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 already signal non-read-only and open-world behavior, and the description adds no further behavioral disclosure. It does not mention that clear/uninstall destroy data, install may fetch remote URLs, or deep_link can wait for activity launch. No contradiction exists, but the description carries little transparency weight.

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

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

The description is a single efficient sentence and lists the main capability areas without filler. It is heavily front-loaded, though the word 'Manage' adds little beyond the action-category list.

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 10 parameters, 10 distinct actions, and no output schema, a one-line description is not enough for an agent to confidently select and invoke the tool. The schema fills in action details, but the description lacks context about destructive operations, prerequisites, and when this tool is the right choice.

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 every parameter. The tool description adds no parameter-specific meaning, which is acceptable at the baseline but not a contributor.

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 concrete domains—lifecycle, installation, state, data, and deep links—so an agent can tell this is the app-level management tool rather than UI, session, or device-control tools. The verb 'Manage' is broad, but the appended resource list gives useful specificity.

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 sibling tools like appium_mobile_device_control or appium_session_management. No exclusions, alternatives, or selection criteria are stated; the agent must infer usage from the action enum.

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?

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 already mark this as readOnlyHint=true, so the safety profile is known. The description adds useful behavioral context: the tool returns an ID for later interactions, xpath is slow and brittle, and platform-specific strategies have different reliability. This goes beyond the annotations without relying on them to carry the whole burden.

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

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

The description is compact and front-loaded: the core action and output are stated first, then strategy ordering, then alternatives. Every sentence contributes either usage guidance, an alternative, or a caveat, with no filler or redundant restatement of the tool name.

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

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

Given the strategy complexity and the lack of an output schema, the description adequately explains the return value and downstream usage. It covers alternatives and selector pitfalls. It does not describe failure behavior (e.g., timeout or not-found), but the read-only annotation and the rich input schema keep this from being a serious gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by giving a concise cross-platform precedence rule ('accessibility id > id > platform-native > xpath') and by warning not to pass natural-language text as a selector. It reinforces and summarizes the schema's parameter guidance rather than merely repeating it verbatim.

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 ('Find an element by strategy and selector') and identifies itself as 'the primary tool for locating a specific target,' clearly distinguishing it from sibling interaction tools. It also states the concrete output (an element ID) and how that output feeds other tools, making the tool's role 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?

Usage guidance is explicit: it gives a locator preference order, names appium_gesture action=scroll_to_element as the alternative when scrolling is needed, and directs natural-language/vision cases to appium_ai action=find_element. It also tells the agent what not to do ('rather than repeatedly calling this tool'), which is strong when-to-use/when-not-to-use guidance.

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

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

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 only indicate readOnlyHint=false and openWorldHint=false. The description adds meaningful behavioral context by explaining the intent behind scroll vs swipe and recommending speed=fast for velocity-sensitive actions. It does not contradict annotations and provides useful semantic guidance, though it omits details like side effects or failure modes.

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 purpose and action list are front-loaded, followed by decision guidance and pointers to sibling tools. 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 tool's complexity (8 actions, 17 params) and full schema coverage, the description covers the key decision points: action selection, scroll/swipe distinction, and alternatives. There is no output schema, so return values are not a gap. The description provides enough for correct invocation.

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

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

Schema description coverage is 100%, so all 17 parameters are fully documented in the schema. The description does not need to repeat parameter details; it only adds a high-level reference to speed=fast, which is also in the schema. Baseline 3 applies because the schema handles the parameter documentation 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 states a specific verb and resource ('Perform a touch gesture') and enumerates the supported actions. It clearly differentiates from siblings by naming appium_drag_and_drop and appium_perform_actions as alternatives for other gesture types.

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

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

Provides explicit guidance on when to use scroll vs swipe (browse vs dismiss/carousel/pull-to-refresh) and calls out alternatives for drag-and-drop and custom multi-touch. This is actionable routing logic an agent can follow without inspecting schemas.

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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that the output is XML and scoped to the current screen, which is useful behavioral context, though it does not mention potential size/latency or failure modes.

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 10-word sentence with no filler. The key information—operation, resource, and format—is immediately front-loaded.

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

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

For a simple read-only tool with one optional sessionId parameter, the description covers the essential operation and return format (XML). No output schema exists, but the 'page source (XML)' phrase sufficiently indicates the return value for a standard Appium agent.

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

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

The sole parameter, sessionId, is fully described in the schema with a default behavior, so schema coverage is 100%. The tool description adds no further parameter insights, hence the baseline score of 3.

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

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

The description uses a specific verb ('Get') and identifies the precise resource ('page source (XML)') plus the scope ('current screen'). This clearly differentiates from siblings like appium_screenshot or appium_get_text, though it does not explicitly name alternatives.

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

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

The description offers no guidance on when to prefer this tool over its many siblings, such as appium_get_active_element or appium_get_window_size. It does not state conditions, exclusions, or alternatives, leaving an agent to infer from the name.

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 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?

The readOnlyHint annotation already covers the non-destructive nature, and the description adds useful behavioral context: a single call can retrieve three different kinds of data selected by the action parameter, and it works across iOS and Android. It does not discuss session behavior, but the schema documents sessionId and its 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?

The description is two short, front-loaded sentences with no filler. The main purpose comes first, followed by the selection mechanism and platform compatibility, so 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 three-parameter read-only tool, the description is complete. There is no output schema, but the input schema's action enum descriptions already specify what 'info', 'battery', and 'time' return, so an agent has everything it needs 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 fully explains the action enum values, the format parameter, and sessionId. The description reinforces that action selects which data to retrieve but adds little beyond the schema, fitting the baseline for fully documented 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 opens with a specific verb and resource: 'Get device information, battery status, or current device time.' It immediately ties these outputs to the action parameterable and clearly distinguishes this read-only device-info tool from the sibling control, text, and element-interaction 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 clearly indicates when to use the tool: whenever the agent needs device info, battery status, or device time, and it notes both iOS and Android are supported. It does not explicitly name alternatives for non-device-info tasks, so it falls short of fully explicit when-not-to-use guidance.

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

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

Annotations show readOnlyHint=false, indicating mutation, which aligns with the push action. The description adds the action-to-payload mapping (push uses payloadBase64, pull returns contentBase64) but does not disclose side effects like file overwriting or failure conditions. It provides some context but is not comprehensive.

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 states the purpose and the key action-to-payload behavior with zero waste. It is efficient and immediately actionable.

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 four parameters and no output schema, the description covers the core behavior and return format for pull. The schema handles platform-specific paths and parameter requirements, so the description is adequate for correct invocation, though it omits error handling and side-effect details.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail, including platform-specific remotePath formats. The description only restates the action-payload relationship already present in the schema, adding no extra semantic value beyond 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?

The description clearly states the action ('push or pull a file') and the specific Appium mobile extensions, making it distinct from other appium_* tools like screenshot or clipboard. It names the resource and the operation precisely, avoiding tautology.

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 by the tool's purpose, but the description does not explicitly state when to choose this over alternatives or provide any exclusion criteria. Since it is the only file-transfer tool among siblings, the choice is obvious, yet the guidance is not explicit.

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

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

Annotations 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 only say readOnlyHint=false and openWorldHint=false, so the description carries the burden of disclosing mutation behavior. It does disclose that 'update' grants/revokes and 'reset' restores a privacy prompt, and it notes platform-specific defaults (Android defaults to the app under test; iOS requires an ID). It does not mention side effects like whether reset clears all prompts or whether update is destructive, but the action-specific parameter hints cover the main behavioral traits.

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

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

The description is a single sentence that front-loads the core purpose and then points to action-specific parameters. It is compact and avoids repeating schema details. It could be slightly more structured (e.g., bullet points per action), but it earns its place and is not bloated.

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

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

Given the tool's complexity (10 parameters, nested objects, three actions, two platforms) and no output schema, the description is reasonably complete: it names the actions, platforms, and points to parameter details. It does not explain return values or error cases, but the schema covers parameter semantics and the description covers the action matrix. A short note on output shape would push it to 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by grouping parameters by action ('iOS update only', 'Android update only', 'Android get only') and by clarifying defaults (Android defaults to the app under test; pm target default). This goes beyond the schema's per-parameter descriptions and helps an agent pick the right parameters for a chosen action.

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 pair ('Get/update Android app permissions or iOS Simulator privacy services; reset iOS privacy prompts') and clearly distinguishes the three actions. It also names the platform split (Android vs iOS Simulator), which differentiates it from sibling tools like appium_mobile_device_control or appium_driver_settings.

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

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

The description gives clear context for when to use the tool (permissions/privacy services) and points to action-specific parameters, but it does not explicitly state when not to use it or name alternative tools. The sibling list contains related device-control tools, but no exclusion is stated.

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

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

Annotations already 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 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 provide readOnlyHint=false and openWorldHint=false, so the description is not required to restate those. It does add meaningful behavioral context by labeling the tool as 'raw' and contrasting it with appium_gesture's automatic platform handling, implying this tool does not abstract platform differences. This informs the agent of potential platform-specific behavior. No contradiction with 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?

Two sentences with zero fluff. The first sentence states the purpose and scope, the second gives usage guidance and alternatives. Critical information (the contrast with appium_gesture) is front-loaded, and every word earns its place.

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

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

Given the complexity of raw W3C Actions API, the description is complete for an agent to decide when to invoke it and what to expect. It covers the tool's niche, its relationship to the sibling, and the key concept of multi-touch via multiple input sources. The detailed schema handles the technical specifics, so the description fills the conceptual gap adequately.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds conceptual value beyond the schema by explaining how multiple pointer sources enable multi-touch gestures and that all sources execute in parallel synchronized tick-by-tick. This helps an agent understand the semantics of the actions array without opening the schema, though it doesn't introduce new parameter-specific details beyond the schema.

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

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

The description opens with a specific verb ('Execute') and a specific resource ('raw W3C Actions API sequences'), and immediately distinguishes itself from appium_gesture by noting it covers gestures 'not covered by appium_gesture'. This makes the tool's purpose unambiguous and separates it from the sibling without requiring schema inspection.

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

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

The description explicitly tells the agent when to use this tool (custom multi-finger gestures, complex timing, precise control) and when to prefer the alternative ('Prefer appium_gesture for standard gestures...'). It also explains why (appium_gesture handles platform differences automatically). This is clear, actionable routing with no ambiguity.

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

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

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?

The description adds the useful behavioral fact that stopping the recording saves it as an MP4, which goes beyond the readOnlyHint=false annotation. However, it does not disclose stateful concerns like the need to pair start with stop, what happens if a recording is already active, or where the file is saved.

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. It front-loads the core purpose and then gives the action-level mechanics, making it easy to scan and process.

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

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

The description is adequate for a basic understanding, and the schema supplies rich parameter detail. However, for a 13-parameter tool with no output schema, it leaves lifecycle behavior, return values, and platform considerations implicit, so an agent gets only partial context.

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 13 parameters. The description mostly restates the action parameter's meaning ('action=start begins recording; action=stop stops and saves to MP4') without adding extra semantics for the platform-specific 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 states a specific verb and resource: start or stop screen recording. It also gives the concrete outcome for stop ('saves to MP4'), which clearly distinguishes this video-capture tool from sibling tools like appium_screenshot.

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

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

The action values make the basic usage clear, but there is no explicit guidance about when to choose this tool over alternatives, nor any documented prerequisites such as an active session or a started recording. Usage is implied 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?

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?

Beyond the annotations (destructiveHint=true), the description discloses lifecycle semantics: detach 'remove[s] an attached session... without deleting the real remote session', delete 'clean[s] up resources' and defaults to the active session, and attach fetches capabilities from the server. These ownership and defaulting behaviors are not encoded in the schema or 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 tool-level description is concise and front-loaded with all six actions. However, the action parameter description is a large wall of text that absorbs nearly all workflow guidance, and the tool description carries little of the load. Every sentence is informative, but the distribution is uneven.

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-action, dual-mode (local/remote) tool with no output schema, the description is remarkably complete: prerequisites, mode selection, parameter roles, and defaults are all covered. Minor gaps remain in return-value shapes (e.g., what create or list returns), but nothing essential to invoking the tool correctly is missing.

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

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

Although schema coverage is 100%, the parameter descriptions add substantial semantics: the action enum embeds complete per-action workflows, sessionId documents default-on-omit behavior per action, capabilities explains serialization rules and precedence, and remoteServerUrl distinguishes local vs remote modes.

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+resource statement ('Manage Appium sessions') and enumerates all six operation modes (create, attach, detach, delete, list, select), each with a distinct purpose. It differentiates cleanly from siblings like appium_app_lifecycle or select_device, which do not manage session lifecycle.

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 action parameter description provides explicit when-to-use guidance: local/embedded mode vs remote server mode, when to call select_device and prepare_ios_simulator first, when to use platform=general, and a concrete example ('create an iOS session at http://localhost:4723'). It also names the alternative preparation tools, leaving nothing to inference.

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

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

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?

The readOnlyHint annotation already covers safety, and the description adds the useful scope 'all interactable elements' and 'current page.' It does not go further into output format, cost/performance, or session requirements, which would add value beyond the annotations.

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

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

The description is a single front-loaded sentence plus a compact usage/priority tag. Every phrase earns its place, and the priority guidance is separated cleanly from the core 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?

For a read-only tool with one optional parameter and no output schema, the description supplies the essential behavior and return concept ('locator suggestions'). It is slightly thin on what the returned locator data looks like, but it is otherwise complete enough to invoke 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%; the only parameter, sessionId, is already documented with 'defaults to active session.' The tool description adds nothing about parameters, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Generate locators for all interactable elements on the current page.' This distinguishes it from sibling tools like appium_find_element (which targets a single element) and appium_get_page_source (which returns raw source rather than locator suggestions).

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 bracketed guidance states concrete use cases: 'debugging/inspection' or needing 'comprehensive element info with locator suggestions.' It does not name alternatives or explicitly state when not to use it, but the context is clear enough for an agent to route to 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 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.