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

The description discloses the behavioral split between mutating actions (accept/dismiss) and a read action (get_text), which adds meaningful context beyond the readOnlyHint=false annotation. It does not contradict the annotations and gives a clear idea of the tool's side effects.

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

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

The description is a single sentence that immediately conveys the purpose and the key action syntax. Every element earns its place with no filler or redundancy.

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

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

For a relatively simple tool with one required enum parameter, the description plus schema covers the main invocation patterns. It does not mention error cases like what happens if no alert is present, but that is arguably beyond the core need for an agent to call 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?

The schema already provides full descriptions for all three parameters (100% coverage), so the baseline applies. The description reinforces the meaning of the action values by noting that get_text reads alert text, but it does not add details about sessionId or buttonLabel beyond the schema.

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

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

The description clearly states a specific operation ('Handle system alerts') and enumerates the exact actions available: accept, dismiss, and get_text. It distinguishes itself from sibling tools like appium_get_text by scoping the operation to system alerts rather than generic element text.

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

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

The description implies when to use the tool: whenever a system alert needs to be accepted, dismissed, or its text read. However, it does not explicitly contrast with alternatives or state when not to use it, leaving some inference to the agent.

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

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

The annotations already indicate readOnlyHint=false and openWorldHint=false, so the description adds little behavioral context. It merely restates broad categories like installation and data without disclosing potentially destructive behaviors (e.g., uninstall, clear data) or side effects beyond what the schema already states.

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

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

One short sentence, front-loaded with the main domain categories. It is compact and easy to parse, though its brevity sacrifices usefulness for a complex multi-action tool.

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 ten parameters, ten possible actions, and no output schema, this one-line description is too thin. It does not explain that the action parameter determines which optional parameters are required, nor does it provide any high-level workflow or caution about destructive actions. The rich schema compensates partially, but the description itself is not contextually complete for real agent use.

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 describes every parameter in detail, including per-action requirements and semantics. The description adds no parameter-level meaning, which matches the baseline for full schema coverage.

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

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

The description lists broad domains (lifecycle, installation, state, data, deep links) so an agent can roughly tell it is an app-management tool, but the verb 'Manage' is vague and does not specify what actual operations are performed. It does not clearly distinguish itself from sibling tools such as appium_mobile_device_control or appium_mobile_permissions.

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

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

No guidance is given on when to use this tool versus alternatives. The description does not name any sibling tools, conditions, exclusions, or prerequisites, leaving the agent to infer usage from the name and schema.

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

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

Annotations indicate readOnlyHint=false, and the description aligns by stating that switch changes the context. It also discloses that list returns both all contexts and the current context. Deeper behavioral details such as switch failure modes or side effects are not covered, but the basic mutation behavior is transparent enough.

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

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

The description is two sentences with no filler. It front-loads the tool's purpose and immediately explains both enum actions, making it quick for an agent to parse.

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

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

The schema covers all parameters, and the description covers the primary behavioral outcomes for both actions. Minor missing details like switch failure behavior or return format are not essential given the schema and annotations present.

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

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

Schema description coverage is 100%, with every parameter already documented including enum values, the context requirement for switch, and the sessionId default. The description adds little beyond restating the action outcomes, which is acceptable given the schema carries the semantic load.

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

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

The description clearly states the tool manages Appium contexts and specifies two concrete actions: list returns all contexts plus the current context, and switch changes to a target context. It distinguishes itself from sibling tools by targeting the context resource, though it does not name an alternative explicitly.

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

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

The description provides internal routing guidance by explaining what each action does, so an agent knows whether to use list or switch. It does not, however, discuss when to prefer this tool over sibling tools or when not to use it.

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

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

Annotations already flag mutation via readOnlyHint=false, and the description adds the full gesture sequence (long press, drag, release) plus default timings of 600ms and 1200ms. It does not cover failure modes or stale-element behavior, but the core interaction model is clearly disclosed.

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 compact, front-loaded sentences cover the action, gesture mechanics, source/target options, and use cases with no filler or redundancy.

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

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

For a gesture tool with a 100%-covered schema, the description supplies the action sequence, timing defaults, coordinate/element alternatives, and practical use cases. The absence of an output schema leaves return behavior unspecified, but this is a minor gap for a UI gesture.

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

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

The input schema documents all 9 parameters with constraints and defaults, so the coverage baseline of 3 applies. The description mostly restates the timing defaults and the element-vs-coordinate option already present in the schema, adding no significant new parameter-level meaning.

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

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

States a specific verb and resource ('drag-and-drop gesture from source to target') and gives distinctive mechanics. It is clearly distinct from generic siblings like appium_gesture and appium_perform_actions, though it does not explicitly name or contrast them.

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 concrete use cases ('reordering lists, moving items, drag-to-delete') that imply when to choose this tool over generic alternatives. It stops short of explicit when/when-not guidance or naming sibling alternatives, so routing is left partly to inference.

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

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

The description adds meaningful behavior beyond the annotations: it explains that get returns JSON, that update performs a merge rather than a full overwrite, and that only sessions supporting Appium settings are applicable. Annotations only provide readOnlyHint=false and openWorldHint=false, so the description carries the behavioral burden and does so reasonably well.

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 focused sentences, with the core operation first, action details second, and applicability third. There is no filler or redundant elaboration; every sentence contributes useful information.

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

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

The description covers the tool's purpose, action modes, supported session types, and the output shape for get. It is slightly less complete for the update path because the return value is not specified, but the schema covers parameter requirements and the overall guidance is sufficient 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 the schema already documents action, settings, and sessionId. The description adds value by giving examples and confirming the merge behavior, but it mostly restates what the schema already says. This matches the baseline for high schema coverage.

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

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

The description clearly states the operation: "Read or update Appium driver session settings" and provides concrete examples like "idle timeouts, selector waits." It is more specific than a bare tool name, though it does not explicitly contrast with sibling tools such as appium_session_management.

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

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

The description gives clear action-level guidance: "Use action=get to return JSON settings; action=update merges a map into the session." It also scopes applicability to embedded UiAutomator2/XCUITest sessions and compatible remote WebDriver clients, but it does not explicitly say when not to use this tool or when to prefer a sibling.

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 read-only, and the description adds behavioral context beyond that: it returns a UUID for later interactions, provides a strategy priority ranking, and warns that xpath is slow and brittle. It does not describe not-found behavior or waiting semantics, but the annotations carry the safety profile.

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

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

The description is well-structured and front-loaded, with the core purpose stated first and clear routing notes following. It is somewhat long and repeats ranking information that also exists in the schema, but every section serves a practical 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 read-only lookup tool with full schema coverage and annotations, the description is largely complete: it defines the return value, strategy selection, and important sibling-tool exclusions. It omits edge-case behavior like 'element not found' or multiple matches, but the core invocation context is covered.

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

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

Schema description coverage is 100%, so the schema already fully documents strategy, selector, and sessionId. The description reinforces the strategy priority and exclusions, but adds little meaning beyond what the parameter 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 and resource: 'Find a specific element by strategy and selector' and adds the key outcome — returning a UUID for interactions. It also distinguishes itself from related tools by naming the scrolling and vision-based alternatives it is not.

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

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

Explicit when-to-use guidance is provided via a strategy priority ordering, and the description clearly says when NOT to use this tool: scrolling should use appium_gesture with scroll_to_element, and natural-language finding should use appium_ai. This is strong routing guidance.

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

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

Annotations already set readOnlyHint=false, so the non-read-only nature is known; description adds that it drives a real session via MCP tools, implying side effects, and clarifies that actual interactions are delegated to sibling tools. It doesn't fully disclose test execution risks, but with annotations that's acceptable.

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

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

Two sentences, front-loaded with purpose and action workflow; the second sentence earns its place by preventing misuse of generate_locators. No fluff.

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 meta-orchestration tool with no output schema, it names the relevant sibling tools and gives an end-to-end flow. Lacks details on the returned instruction format, but that is likely unnecessary for correct invocation, and the one input is fully specified by the schema.

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

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

Schema coverage is 100% and the only parameter, steps, has a clear schema description. The tool description adds no extra parameter detail, so baseline 3 applies.

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

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

States a specific verb+resource ('Generate tests for a mobile app'), then differentiates from generate_locators explicitly and names typical sibling tools for the workflow. An agent can tell what it does and how it relates to adjacent 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?

Gives direct workflow: follow returned instructions, drive session with listed MCP tools, then emit code; also explicitly says when to use generate_locators vs appium_find_element. This is stronger than most – names alternatives and conditions.

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?

While the annotations only declare readOnlyHint=false and openWorldHint=false, the description adds useful behavior: platform support differences, reset unsupported on Android emulators, the suggestion to use set instead, and the note about mocked location persistence on Android real devices. This goes beyond what the annotations or schema communicate.

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 informative without padding; each sentence earns its place. The main action modes are front-loaded, followed by platform caveats. The structure flows logically from overview to usage to edge cases.

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 absence of an output schema, the description could have briefly stated the return shape for action=get, but 'read current coordinates' is reasonably indicative. It covers platform-specific behavior, action semantics, and limitations. The only minor gap is the exact output format for get operations.

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 the action modes and mentions optional altitude, but it does not add substantial meaning beyond the schema's parameter descriptions. The schema already documents required-for-set, ranges, platform applicability, and defaults.

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-plus-resource statement: 'Get, set, or reset the device geolocation (GPS coordinates).' It clearly distinguishes this from other Appium control siblings by naming a unique resource and the three supported operations. The platform coverage statement further disambiguates the tool's scope.

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 conditional guidance: use action=get to read, action=set to simulate, action=reset to restore, and explains when reset is not supported. It does not explicitly name alternative sibling tools, but the geolocation scope is distinctive enough that the intended usage context is clear.

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

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

Annotations only carry readOnlyHint=false and openWorldHint=false, so the description carries much of the disclosure burden. It adds useful context about scroll vs swipe intent and delegates drag-and-drop/multi-touch to siblings, but it does not describe side effects, return values, errors, or prerequisites such as session/element requirements. Most behavioral details live only in the schema parameter descriptions, not in the tool description itself.

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

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

The description is three tight sentences: purpose and action list first, then the scroll-vs-swipe decision rule, then sibling routing. No filler or repetition; 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 high complexity of 17 parameters and no output schema, the definition is nearly complete because the schema descriptions are exhaustive and the tool description handles sibling discrimination. The only gap is that the description does not state what the tool returns or how failures are signaled, which would matter for an agent deciding how to handle 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%, so the schema already documents all 17 parameters in detail. The tool description adds selection guidance but no extra parameter semantics; it does not need to, since the schema fully covers this. 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 ('Perform') and resource ('touch gesture') and immediately lists the supported action variants. It also distinguishes itself from the sibling tools appium_drag_and_drop and appium_perform_actions, making its scope unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Choose scroll vs swipe by intent' and gives concrete use cases for each. It also names alternatives directly: 'For drag-and-drop use appium_drag_and_drop. For custom multi-touch use appium_perform_actions.' This is exactly the routing an agent needs.

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

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

readOnlyHint=true already signals a safe read operation, and the description is consistent with it. Since there is no output schema, the explicit statement that it returns a UUID for follow-up interactions adds genuinely useful behavioral context beyond the annotation.

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

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

Two short sentences: the first states the core action and return value, the second adds a decision rule. No redundant wording or repetition of schema details.

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-optional-parameter read-on ly getter, the description covers what it returns and whe to use it. The only missing context is edge-case behavior when no element is active/focused, but this is a minor gap given the tool's simplicity.

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

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

The schema fully describes the only parameter (sessionId, optional, with its own description), so the description does not need to add parameter-level detail. Baseline of 3 applies because schema coverage is 100%.

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') with a clear resource ('currently active/focused element') and states the output ('its UUID for follow-up interactions'). This clearly distinguishes it from siblings like appium_find_element, which locates elements by criteria rather than returning the focused one.

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 PRIORITY 1 note gives an explicit condition for when to use this tool ('when you need to find what element currently has focus'). It does not name alternatives or state when not to use it, so it stops short of a full when/when-not guide.

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, so the read-only nature is covered. The description adds usage context but does not disclose behavioral details such as whether an invalid attribute returns null, empty string, or an error, nor any platform-specific quirks. This is acceptable but not richly transparent.

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

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

Two tight sentences with no filler. The core operation is front-loaded, and the usage examples are immediately useful without unnecessary elaboration.

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 getter with fully described parameters and a clear annotation, the description and schema together provide sufficient context to call the tool. The main gap is the lack of explicit return/error behavior, but 'Get the value' conveys the core return semantic, making this near-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 coverage is 100%, so the baseline is 3. The description adds value by grouping attributes into state checks versus property reads, which helps the agent choose meaningful attribute names. It does not add meaningful new information about sessionId or elementUUID beyond what the schema already states.

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

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

The description clearly identifies the operation as retrieving an element attribute value and provides concrete examples (enabled, selected, checked, content-desc, resource-id). This makes the purpose understandable and distinct from generic page-source or screenshot tools, though it does not explicitly distinguish it from the sibling appium_get_text.

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

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

The phrase 'Use this to check element state... or read properties' gives explicit guidance on when to apply the tool. However, it does not mention alternatives or conditions when another tool like appium_get_text should be preferred, so it stops short of a full 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 readOnlyHint annotation already signals safety, and the description adds that the result is XML and tied to the current screen. However, it does not disclose contextual behaviors such as whether the source can be large, whether accessibility data is included, or what happens when no session exists. It does not contradict the annotations.

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

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

The description is a single front-loaded sentence with no filler: verb, object, format, and scope are all present. Given the simple schema, this is appropriately concise.

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 operation with one optional parameter, the description and schema cover the essential call information. It identifies the return format as XML and the schema handles session targeting; no critical detail needed to invoke the tool is missing.

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

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

Schema description coverage is 100% for the single optional sessionId parameter, and the schema already explains the active-session fallback. The description adds no parameter-specific 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 clearly states a specific verb and resource: 'Get the page source (XML) from the current screen.' It is unambiguous and easy for an agent to act on, though it does not explicitly differentiate itself from sibling tools that inspect UI content.

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

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

No guidance is given about when to prefer this over alternatives like appium_get_text, appium_find_element, or appium_screenshot. There is also no mention of prerequisites such as an active session or when the full XML source is the appropriate choice.

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

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

With readOnlyHint=true in annotations, the safety profile is already known. The description adds no behavioral context beyond the annotation - it doesn't explain return format, behavior on missing elements, or whether hidden text is included. Since the description adds nothing beyond the structured fields, it falls short of the baseline.

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

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

The description is a single clear sentence with no wasted words. It is efficient and front-loads the core action, though it could be expanded with useful context without becoming verbose.

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 getter with two parameters and readOnlyHint annotation, the description is minimally adequate. However, with no output schema, it fails to mention the return type (string) or any edge-case behavior, and it doesn't differentiate from get_element_attribute, leaving some ambiguity for an agent deciding how 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%, with both sessionId and elementUUID documented. The description itself doesn't add parameter-level meaning, but the schema already explains that elementUUID comes from appium_find_element. Baseline 3 is appropriate because the schema carries the semantic weight.

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 'Get text from an element' uses a specific verb and resource, clearly indicating the tool retrieves the text content of a UI element. It is distinguishable from siblings like appium_get_element_attribute and appium_get_active_element, though it doesn't explicitly state those distinctions.

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

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

No guidance is provided about when to use this tool versus alternatives such as appium_get_element_attribute. The only implied usage is through the elementUUID parameter description referencing appium_find_element, but the tool description itself lacks any when-to-use or exclusion context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the unit and use-case context but does not disclose return shape or orientation-dependent behavior; this is acceptable but not especially 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 concise sentences, front-loaded with the core action and result, followed by a practical use case. Every word earns its place with no redundancy.

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

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

The tool has a single optional parameter documented in the schema, and the description explains what it returns (width and height in pixels) and why it is useful. It is nearly complete, though a note about orientation or return field names would make it fully self-contained without 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 description coverage is 100%, with the only parameter (sessionId) already explained as optional and falling back to the active session. The description adds no parameter-specific meaning, matching the baseline for fully documented schema 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 tool retrieves screen width and height in pixels, naming a specific resource ('device screen') and unit. It is readily distinguishable from gesture/coordinate tools, though it does not explicitly contrast with appium_mobile_device_info, which could also expose screen-related info.

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

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

The description gives clear usage context: this is for calculating coordinates for swipes, taps, and scrolls. It does not mention exclusions or alternative tools, but for a simple read tool the intended use is easy to infer.

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 (readOnlyHint false, openWorldHint false), the description discloses the two operational modes and the dependency between action and content. It could add side-effect or error context, such as overwriting existing clipboard contents, but it still provides meaningful behavioral clarity.

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

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

One compact sentence delivers the verb, resource, scope, platform support, and action-specific behavior without any filler. It is front-loaded and every clause 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 description plus the fully documented schema is enough for an agent to correctly invoke get or set. Some details are missing, such as return behavior nuances or failure conditions, but the tool is simple and the description covers the essential invocation logic.

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 and the action/content dependency. The description reinforces these semantics but does not add new parameter-level meaning beyond what the schema provides.

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

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

The description states a specific action ('Read or set') on a specific resource ('device clipboard as plain text') and names the supported platforms. This clearly differentiates it from sibling tools focused on elements, gestures, or device control.

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 action-level guidance: use 'get' to read and 'set' to write, with content required for 'set'. It does not explicitly mention alternatives or exclusions, but no sibling tool appears to compete with clipboard functionality, so the context is sufficient.

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 a mutating operation (readOnlyHint=false), and the description aligns by naming state-changing actions. It adds modest context by specifying screen lock/unlock and device shake, but it does not disclose platform restrictions, side effects, or session targeting behavior beyond what the schema already states.

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 core action list is front-loaded and the action parameter guidance is relevant. It is appropriately compact, though 'Control device behavior' is slightly redundant with the listed actions.

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 three-parameter action selector with no output schema, the description plus schema is adequate. Still, the description alone omits the lock-duration parameter and session targeting, and there is no behavioral detail about return values or effects, so it is not 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 the parameter baseline is 3. The description's 'Use the action parameter to choose what to do' adds little beyond the schema's already detailed enum, and it does not mention the optional seconds or sessionId 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 enumerates four concrete device actions—lock/unlock the screen, shake, open notifications—which clarifies what the tool does. 'Control device behavior' is somewhat general, but the explicit list disambiguates it from most 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?

The action list implies when to use the tool: whenever the needed operation is lock, unlock, shake, or open_notifications. However, it does not explicitly contrast this with siblings like appium_gesture or appium_orientation, nor does it state when not to use it.

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

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

Annotations already carry the readOnlyHint=true safety profile, so the description only needs to add behavioral context, and it does add some: the 'single call' efficiency trait and the cross-platform scope ('Works on both iOS and Android'). However, it does not disclose edge behaviors like session requirements, error cases, or permission needs; these are not critical given the read-only profile but prevent a higher score.

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

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

Three short sentences with the core purpose front-loaded. The platform note ('Works on both iOS and Android') adds genuine value, while the action-parameter sentence is mildly redundant with the schema but still concise. No wasted words overall.

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

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

For a low-complexity read-only tool (one required param, no output schema), the package is complete: the description covers the purpose and platform scope, and the schema fully documents parameter semantics including return-value descriptions via the action enum. The only notable gap is the absence of sibling-selection guidance, which is already counted 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%, and the schema already documents each parameter in detail, including the enum meanings for action ('info' returns device model/OS/locale/etc., 'battery' returns battery level and charging state, 'time' returns current device time) and the sessionId fallback behavior. The description's 'Use the action parameter' line merely restates the schema, adding no 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 names a specific verb ('Get') and resource ('device information, battery status, or current device time'), and explicitly enumerates the three retrievable data types. This clearly distinguishes it from siblings like appium_mobile_device_control and select_device, which cover control and selection rather than info retrieval.

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

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

Usage is implied rather than explicit: an agent can infer to use this when device info, battery, or time is needed, but there is no when-not-to-use guidance or alternative routing. The sentence 'Use the action parameter to select which data to retrieve' explains in-tool parameter behavior, not tool selection. With 30+ siblings, explicit exclusion guidance would have helped.

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

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

Annotations already indicate the tool is not read-only (readOnlyHint=false) and has no open-world hint, so the description carries the burden of behavioral detail. It adds action-specific behavior: 'action=push uses payloadBase64, action=pull returns contentBase64.' This is useful but still does not describe side effects, failure modes, or limitations. It does not contradict the annotations.

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

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

The description is two short sentences with no filler. The core purpose is front-loaded, and the action-specific input/output behavior is summarized efficiently. Every clause carries useful information.

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

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

Given the full parameter schema, including platform-specific remotePath guidance, the description is nearly complete for invoking correctly. It additionally supplies the missing output clue for pull ('returns contentBase64'). A minor gap is the lack of any note about push response/errors, but this does not seriously impair 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 the baseline is 3. The description adds no real parameter semantics beyond mentioning payloadBase64's role, which the schema already documents. remotePath and sessionId semantics are fully handled by the schema, not enhanced by the description.

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 pair: 'Push or pull a file using Appium mobile extensions.' It then explicitly names the two actions ('push' and 'pull') and their data flow, making it easy to distinguish from sibling tools that handle gestures, clipboard, screenshots, or device controls.

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

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

Usage context is implied: if an agent needs to transfer a file to or from a device, this is the tool. However, the description does not explicitly state when to use it versus alternatives, nor does it mention prerequisites like having an active session or selecting a device, leaving some inference to the agent.

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

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

The description discloses the underlying protocol commands (mobile: hideKeyboard and mobile: isKeyboardShown), platform support, and the fact that keys are only honored for hide. This adds meaningful behavioral detail beyond the sparse annotations, though it does not mention error cases or return values.

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

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

The description is two sentences with no filler. It front-loads the primary purpose and then compactly explains the two action modes, making it quick for an agent to parse.

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

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

For a simple two-action utility, the description plus the 100% schema coverage provides enough information to invoke the tool correctly. It lacks an explicit return type for is_shown, but the overall context is still sufficiently 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 fully documents action, keys, and sessionId. The description mostly reinforces the schema rather than adding new semantic detail, which fits the baseline 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 states a clear, specific purpose: hide the software keyboard or check whether it is visible. It also names the two supported platforms and the underlying mobile commands, making it easy to distinguish from siblings 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 explicitly maps each action value to its behavior and mobile command, giving the agent clear guidance on how to choose between hide and is_shown. It does not explicitly discuss when to prefer sibling tools, but the tool's purpose is distinct enough that the usage context is clear.

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

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

Annotations only provide readOnlyHint=false, so the description carries the burden of behavioral disclosure. It discloses that 'reset' affects iOS privacy prompts and that 'update' modifies permissions, but it does not specify side effects, requirements (e.g., simulator must be booted), whether changes persist, or what happens to existing settings. The description adds some context beyond the annotations but omits important behavioral details.

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

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

The description is one efficient sentence that front-loads the core verbs and resources, then points to the schema for details. Every clause carries meaning; there is no filler or redundancy. The structure is ideal for a tool with a rich 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?

Given the tool's complexity (10 parameters, nested objects) and the absence of an output schema, the description alone is not enough to fully understand invocation. However, the schema descriptions fill most gaps. The main missing context is return values and side effects, neither of which is covered by the description or an output schema. The 'See action-specific parameters' hint guides the agent to the schema, but the description does not stand 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%, so every parameter is already explained in the input schema. The description adds only a pointer ('See action-specific parameters'), which is useful but does not enhance the parameters' meaning beyond what the schema provides. 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 the specific verbs 'Get/update' and 'reset' against concrete resources ('Android app permissions', 'iOS Simulator privacy services', 'iOS privacy prompts'), and scopes the platform split. This is a clear verb+resource statement that differentiates the tool from sibling tools like appium_mobile_device_control or appium_driver_settings, which do not mention permissions.

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

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

The description implies use cases by stating the platforms and actions but does not explicitly route to an alternative or state when not to use it. It only points to 'action-specific parameters' in the schema. There are no exclusionary clauses or named alternatives among the siblings, so usage is inferred rather than directly guided.

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 behavioral context beyond the readOnlyHint=false annotation by specifying platform-specific key support (Android vs iOS/tvOS). However, it does not disclose side effects, error behavior, or precedence rules (e.g., keyCode overrides key), though some of those are present in the schema. 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?

The description is a single, concise sentence with no filler. It front-loads the core action and immediately gives useful platform distinctions, making efficient use of every word.

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 relatively simple action tool with full schema coverage of parameters and no output schema, the description sufficiently states the purpose and platform behavior. It lacks explicit alternative routing, but the core information an agent needs to invoke the tool is present.

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

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

Schema description coverage is 100%, so the schema already explains all four parameters. The description adds no parameter-specific meaning beyond the platform mapping already present in the key field's enum description, 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 uses a specific verb ('Press') and names the resource ('navigation keys', 'physical buttons'), and it clarifies platform differences. It distinguishes itself from likely siblings like appium_gesture or appium_mobile_keyboard by focusing on hardware/navigation keys, though it does not explicitly name an alternative.

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

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

There is no guidance about when to use this tool versus alternatives such as appium_mobile_keyboard or appium_gesture. The description states what the tool does but gives no explicit when/when-not context or comparison with sibling tools.

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 openly indicates both a read operation (get) and a mutating operation (set), which aligns with readOnlyHint=false. It also communicates the allowed orientation values. While it does not go deep into side effects or failure modes, the behavior is clear enough for this simple tool and the annotations already signal mutability.

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 primary action front-loaded. It conveys the tool's purpose and supported values with no wasted words.

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

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

For a simple three-parameter tool with a complete schema, the description covers the essential behavior and valid actions. The only minor gap is that no return value format is described, but the absence of an output schema and the straightforward nature of orientation get/set reduce the importance of that omission.

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 (action, sessionId, orientation) are already documented in the schema. The description adds no significant parameter meaning beyond restating the action values, 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 clearly states the verb (get or set) and the resource (device/screen orientation), and explicitly lists the supported action values. It is immediately distinguishable from sibling tools like appium_get_window_size or appium_mobile_device_control because the resource is named precisely.

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: use this tool when you need to read or change the device/screen orientation. It does not explicitly name alternatives or exclusion cases, but the narrow scope and explicit action values make the intended usage unmistakable.

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 the tool is not read-only, and the description conveys that it executes raw action sequences with side effects. It does not add much behavioral context beyond that, such as potential device-state changes or return behavior, though the raw API framing makes the mutating nature clear.

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, zero filler, with the core purpose front-loaded and the routing instruction placed clearly at the end. 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 raw API tool, the description plus a fully documented schema gives an agent enough to invoke it correctly. The main gap is that it does not describe what kind of result or acknowledgement the raw API returns, but the absence of an output schema makes that a minor omission.

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

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

Schema description coverage is 100%, with thorough documentation for input sources, action types, coordinates, durations, and origin. The description contributes gesture-level context but does not need to explain individual parameters because the schema already carries the full semantic load; 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 opening clause states a specific verb and resource ('Execute raw W3C Actions API sequences') and immediately differentiates it from appium_gesture. Concrete use cases are listed, so an agent can clearly tell this is for advanced, custom multi-touch gestures rather than standard ones.

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 when-to-use guidance: custom multi-finger gestures, complex timing sequences, or precise control over touch points. It also explicitly tells the agent to prefer appium_gesture for standard gestures because it handles platform differences automatically.

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 are minimal (readOnlyHint=false, openWorldHint=false), leaving the description to carry the burden — and it delivers. It discloses cache semantics (WDA download and unsigned IPA cached per version, signed IPA rebuilt every call), mode-dependent side effects (list-only vs download/package/resign), wildcard profile handling with bundle ID substitution at sign time, and the external toolchain requirements. Nothing here contradicts readOnlyHint=false.

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?

Longer than a typical tool description, but the tool genuinely warrants it — a two-mode flow, caching behavior, signing mechanics, and a cross-tool handoff all need explaining. The purpose is front-loaded, the modes are numbered for easy parsing, and every sentence (prerequisites, cache rules, capabilitiesHint routing) carries information without repeating 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?

With no output schema and sparse annotations, the description compensates well: it states what mode 1 returns (profile list with recommendedForWda flags), what mode 2 returns (capabilitiesHint), the prerequisites, and the downstream call. The residual gaps are the full response envelope shape and failure cases (e.g., no profiles found, device not paired), which an output schema would normally cover.

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%, which sets a baseline of 3, but the description adds meaning above the schema: it explains the two-mode flow keyed to provisioningProfileUuid presence, the wildcard ('*') profile substitution detail, and how forceRebuild interacts with the per-version cache of the WDA download and unsigned IPA. It also clarifies the capabilitiesHint output contract that connects to session creation.

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

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

Opens with a specific verb+resource statement — 'Prepare an iOS real device for Appium testing in a single call' — then details a concrete two-mode mechanism, so there is no ambiguity about what the tool accomplishes. It is clearly distinguished from siblings: appium_session_management is positioned as the downstream consumer of capabilitiesHint, select_device is referenced for UDID discovery, and the real-device provisioning focus sets it apart from prepare_ios_simulator.

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 an explicit usage sequence: first call without provisioningProfileUuid to obtain the profile list, present it to the user, then call again with the chosen UUID. It also states hard prerequisites (macOS, Xcode 16+, paired developer-mode device) and routes the output to appium_session_management with action=create. It does not explicitly name when-not cases or alternatives, so it misses the top of the scale.

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 non-read-only, so the description carries the burden of explaining the mutation. It adds meaningful behavioral detail: 'action=start begins recording; action=stop stops and saves to MP4.' This goes beyond the annotation by specifying the two-phase lifecycle and the save-on-stop behavior, which is essential for correct invocation.

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 is front-loaded and the action mapping is immediately clear. Every word contributes to understanding the tool's core function.

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 (14 parameters) and rich per-parameter schema descriptions, the concise description is largely sufficient. It captures the key start/stop workflow and MP4 output. Minor missing high-level context, such as the need to call stop even after timeLimit, is already explained in the schema parameter description, so the description does not need to duplicate it.

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

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

Schema description coverage is 100%, so the baseline is 3. The main description merely repeats the action enum and its meaning already present in the schema; it does not add semantics for the other 13 parameters. No extra value beyond the detailed property 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 states a specific verb and resource: 'Start or stop screen recording.' It clearly identifies the two supported actions (start/stop) and the output format (MP4). This distinguishes it from siblings like appium_screenshot, since screen recording is a distinct video-capture operation.

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 when to use the tool: when you need to begin or end a screen recording. However, it gives no explicit guidance about when not to use it or which sibling alternative to choose (e.g., appium_screenshot for still images). The usage context is clear but not oriented against other tools.

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 a meaningful side effect: the screenshot is saved as a PNG file, which is useful given readOnlyHint=false. However, it does not say where the file is saved, what response shape to expect, or how returnRawBase64 changes the behavior beyond what the schema already states. Some behavioral context is present but incomplete.

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 concise and front-loaded: the main action and output format appear first, followed by a single optional-behavior sentence. There is no redundant wording or 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?

This is a simple zero-required-parameter tool, and the input schema richly documents all parameters including the LLM-specific returnRawBase64 guidance. The description could have stated the returned file path contract explicitly, but the schema's reference to 'saved file path' plus the 'save as PNG' side effect make it sufficient 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 four parameters are already documented. The description adds only a simple restatement of elementUUID's optional capture behavior, which provides marginal value beyond the schema but does not introduce any new parameter semantics.

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

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

The description clearly states the action ('Take a screenshot') and the output format ('save as PNG'), and it mentions the optional element-scoped capture mode. It does not explicitly differentiate from sibling appium_screen_recording or other capture tools, but the core purpose is 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 no guidance on when to prefer this tool over alternatives such as appium_screen_recording, nor does it mention exclusions or prerequisites. The only usage hint is the optional elementUUID behavior, which is more of a parameter detail than a tool-selection guideline.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=true, so the agent knows this tool can mutate state. The description adds a small behavioral distinction between detach ('forget') and delete ('stop'), which is useful. However, it does not disclose important traits such as attach not taking ownership of the remote session lifecycle or detach leaving the real remote session intact—details that would prevent misuse and are only found in the parameter schema.

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

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

The description is a single, front-loaded sentence that states the general purpose and enumerates all actions without filler. It is compact and easily scannable. It is slightly run-on, but every clause earns its place, so the efficiency is strong.

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

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

For a multi-action tool with five parameters, the full definition is quite complete: the action parameter description covers local vs remote modes, prerequisites (select_device, prepare_ios_simulator), explicit prohibitions ('NEVER invent a localhost URL'), and examples. The tool description alone is thin, but the schema richness compensates. The absence of an output schema is partially mitigated by the list action describing its returned fields, though create/select return shapes are not described.

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 complete parameter descriptions in the schema (modes, examples, JSON serialization, required capabilities for attach) already carry the full semantic load. The tool description itself does not add parameter meaning, but given the high coverage, no further description contribution is required.

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

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

The description names the resource (Appium sessions) and lists six concrete actions (create, attach, detach, delete, list, select), so the tool's scope is clear and visibly distinct from device-control, element, and file siblings. The verb 'Manage' is generic, but the action enumeration compensates and gives the agent a precise idea of what the tool does. It does not explicitly name an alternative sibling, so a 5 is not warranted.

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

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

The description gives no guidance on when to use this tool versus siblings like select_device, prepare_ios_simulator, or the appium_* device-control tools. It only implies that session management is its job. Although the action=create parameter description later provides rich workflow rules (e.g., 'Use select_device tool FIRST', 'SKIP select_device tool entirely'), that guidance is not in the tool description itself, and the description carries no exclusions or alternatives.

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

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

Annotations only indicate a non-read-only action, and the description adds little behavioral detail. It does not disclose whether text replaces existing content, whether the element must have focus, whether automation must wait for visibility, or how failures behave. Some useful behavior appears in the w3cActions parameter description, but not in the tool description itself.

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 a clear verb and object. There is no filler or redundant information, making it highly concise.

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

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

Although the schema documents parameters well, the tool lacks usage context, preconditions, and sibling differentiation. Given the large set of related Appium input and action tools, an agent could easily call the wrong one without additional guidance.

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

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

The input schema provides 100% coverage with descriptive entries for all four parameters, including the detailed w3cActions flag. The description itself adds no parameter-level meaning, but this is acceptable because the schema already carries that 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 clearly states the action ('Enter text') and the resource ('an element'), so an agent can tell that this is a text-input operation. However, it does not differentiate it from sibling input tools like appium_mobile_keyboard or appium_perform_actions.

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 use this tool instead of related tools such as appium_mobile_keyboard, appium_mobile_press_key, or appium_perform_actions. The description implies text entry but provides no conditions, prerequisites, or exclusions.

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

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

Annotations already mark this as read-only and not open-world. The description adds useful scoping context ('current page', 'all interactable elements') but does not disclose details like output structure, failure behavior, or performance characteristics. There is 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?

The description is compact and front-loaded: the core purpose comes first, followed by a concise usage hint. Every part contributes actionable 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?

The tool is low-complexity: one optional, fully documented parameter, read-only annotations, and no nested schema. The description covers purpose and when to use it. It could describe the exact return format more explicitly, but for a debugging/inspection tool this is largely 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?

There is only one parameter, sessionId, and the schema description fully explains it: 'Session ID to target. If omitted, uses the active session.' With 100% schema coverage, the description does not need to add parameter-level meaning.

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

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

The description uses a specific verb and resource: 'Generate locators for all interactable elements on the current page.' It clearly conveys what the tool does and the output type (locators + element info). It does not explicitly distinguish itself from sibling tools like appium_find_element, but the 'all interactable elements' scope is reasonably distinctive.

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 note explicitly gives usage context: 'Use this for debugging/inspection or when you need comprehensive element info with locator suggestions.' This is clear and actionable, though it does not mention when not to use the tool or name alternative tools.

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 sparse annotations, the description reveals that the tool boots simulators, downloads prebuilt WDA when not cached, installs/launches it on a per-simulator free port to avoid 8100 collisions, and can skip WDA via flags or env var. The side-effecting nature is consistent with readOnlyHint=false, and no statement contradicts openWorldHint=false.

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?

Every sentence delivers distinct information: the one-line purpose, the behavioral/parallelism detail, the downstream session hand-off, the skip-WDA switch, and the env-var fallback. It is dense but 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 there is no output schema, the description still tells the agent what the tool returns (capabilitiesHint containing appium:webDriverAgentUrl) and how to consume it. It also covers the boot/no-WDA/offline-download cases an agent is likely to need, making the description sufficient 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?

The schema already documents all four parameters (100% coverage), so the description's job is additive. It adds practical context for skipWda=true (boot-only mode) and introduces the APPIUM_MCP_WDA_APP_PATH environment variable, which is absent from the schema but materially affects download behavior. Platform and forceRefreshWda are not expanded beyond schema, so a 4 rather than 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?

The description uses a specific verb ('Prepare') and resource ('iOS/tvOS simulator'), and states the intended outcome ('for Appium testing in a single call'). It also names concrete actions (boots, downloads, installs/launches WDA) that distinguish it from session management and real-device preparation 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?

It explicitly provides workflow guidance: the returned capabilitiesHint should be passed to appium_session_management(action=create) to reuse WDA rather than start a new one. It also gives conditional usage for skipWda=true and APPIUM_MCP_WDA_APP_PATH, including the environment where downloads are blocked.

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

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

Annotations are minimal (readOnlyHint false, openWorldHint false), so the description carries the behavioral burden. It discloses key traits: the tool auto-selects when only one device is found, requires a second call with deviceUdid when multiple are found, and must not be used for remote servers. It does not explicitly describe the return format or what happens if no devices are found, but the workflow is otherwise transparent.

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

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

The description is longer than average, but highly structured with clear workflow numbering and front-loaded local/remote distinction. Minor redundancy exists in repeated references to appium_session_management (action=create) and prepare_ios_simulator, but these repetitions reinforce the handoff rather than adding noise.

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 no output schema, the description covers nearly everything an agent needs: local vs remote handling, user-asking requirements, auto-selection behavior, re-call semantics, and follow-up steps. It is slightly incomplete in not describing the tool's response shape or fallback behavior when zero devices are found, but those are secondary given the explicit workflow.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful usage sequencing: call first with just platform (and iosDeviceType for iOS), then call again with deviceUdid if multiple devices are found. It also reinforces that iosDeviceType is required for iOS, going slightly beyond the static schema.

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

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

The description clearly states the tool's specific purpose: 'Discover and select a device for LOCAL Appium servers ONLY.' It explicitly distinguishes the tool from remote-server workflows and names sibling tools like appium_session_management and prepare_ios_simulator, so an agent can reliably tell when to use it.

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

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

Usage is exceptionally well specified. It says 'DO NOT use this tool for REMOTE Appium servers' and gives the exact alternative ('handled via capabilities on appium_session_management'). The numbered local workflow tells the agent when to call, when to ask the user, when to re-call with deviceUdid, and what to do next.

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