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

With no annotations, the description carries full burden but only states the action without behavioral details. It doesn't disclose risks (e.g., destructive commands, permissions needed), output format, error handling, or rate limits, which are critical for an arbitrary shell command tool.

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

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

The description is a single, direct sentence with zero wasted words, making it highly concise and front-loaded. It efficiently conveys the core purpose 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?

Given the tool's complexity (arbitrary shell execution) and lack of annotations/output schema, the description is insufficient. It doesn't cover safety, output expectations, or error cases, leaving significant gaps for agent usage despite good schema coverage.

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

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

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds no extra meaning beyond implying 'command' is arbitrary and 'device_id' is optional for single devices, matching schema details. Baseline 3 is appropriate as schema does the work.

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 ('Run') and target ('ADB shell command'), making the purpose evident. However, it doesn't differentiate from siblings like 'clear_logs' or 'get_device_info', which are more specific ADB operations, so it's not a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios where this general-purpose command is preferred over specific sibling tools like 'install_apk' or 'get_logs', leaving the agent to guess based on 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool clears a buffer (a destructive action), which is useful behavioral context. However, it lacks details on permissions needed, error conditions, or what happens if no device is specified, leaving some behavioral aspects unclear.

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 that are front-loaded with the core action and followed by usage guidance. Every word earns its place, with no redundancy or fluff, making it highly efficient and easy 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?

Given the tool's moderate complexity (a destructive operation with one optional parameter) and no annotations or output schema, the description does well by stating the purpose and usage context. However, it could improve by mentioning potential side effects or confirmation of success, leaving minor gaps in completeness.

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

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

The input schema has 100% description coverage, so the schema already documents the optional 'device_id' parameter. The description does not add any parameter-specific information beyond what the schema provides, but since there's only one parameter and it's optional, the baseline is high. No additional semantic value is added, but the schema suffices.

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 specific action ('Clear the logcat buffer') and resource ('logs'), distinguishing it from sibling tools like 'get_logs' which presumably retrieves logs rather than clearing them. It provides a concrete verb+resource combination that 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 explicitly states when to use this tool: 'before reproducing a bug to get clean logs.' This provides clear context for usage and implicitly suggests alternatives (e.g., not using it when you want to preserve existing logs), making it highly actionable for an 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?

With no annotations provided, the description carries full burden but offers minimal behavioral insight. It doesn't disclose whether this is a read-only operation, if it requires specific permissions, potential latency, or error conditions (e.g., device not found). The phrase 'currently displayed' implies real-time data but lacks detail on freshness or constraints.

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

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

The description is a single, efficient sentence with zero wasted words. It front-loads the core purpose ('Get the currently displayed app and activity'), making it immediately actionable 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?

Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., app name, activity class, timestamp) or how to interpret results, leaving significant gaps for an AI agent to understand the tool's full behavior and output.

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 fully documents the optional 'device_id' parameter. The description adds no parameter-specific information beyond what's in the schema, but it doesn't need to compensate for gaps, meeting the baseline for high 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 action ('Get') and the target ('currently displayed app and activity'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_device_info' or 'get_ui_tree', which might also provide related information about the device state.

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 on when to use this tool versus alternatives like 'get_device_info' or 'get_ui_tree'. The description lacks context about prerequisites (e.g., device connectivity) or typical use cases (e.g., debugging app interactions).

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions what details are retrieved but does not cover aspects like whether this requires device connectivity, permissions, or error handling. For a tool with no annotations, this leaves significant gaps in understanding its operational behavior.

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

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

The description is a single, efficient sentence that lists the key details retrieved without unnecessary words. It is front-loaded with the core purpose and provides specific examples, making it easy to understand quickly with zero waste.

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

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

Given the tool's low complexity (one optional parameter) and no output schema, the description covers the basic purpose and attributes. However, with no annotations and sibling tools present, it lacks context on prerequisites, errors, or how it fits into broader workflows, making it minimally adequate but with clear gaps.

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

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

The input schema has 100% description coverage, with the parameter 'device_id' documented as optional. The description does not add any meaning beyond this, such as explaining default behavior when no device_id is provided. Given the high schema coverage, a baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.

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

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

The description clearly states the verb 'Get' and the resource 'device details', listing specific attributes like model, manufacturer, and Android version. However, it does not explicitly differentiate this tool from sibling tools like 'list_devices' or 'get_current_activity', which might also provide device-related information, leaving some ambiguity about its unique role.

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 no guidance on when to use this tool versus alternatives. With sibling tools such as 'list_devices' and 'get_current_activity', there is no indication of whether this tool is for detailed static info, current state, or other contexts, leaving the agent to infer usage without explicit direction.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool is for 'Get' operations, implying read-only behavior, but fails to disclose critical traits like whether it requires specific permissions, has rate limits, or what the output format looks like (e.g., text, JSON). This leaves significant gaps for a tool with no annotation coverage.

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 highly concise and front-loaded, consisting of two sentences that directly state the tool's purpose and usage context without any wasted words. Every sentence earns its place by providing essential information efficiently.

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

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

Given the complexity (5 parameters, no output schema, no annotations), the description is minimally adequate. It covers the purpose and basic usage but lacks details on behavioral traits, output format, and deeper context needed for full understanding. With no output schema, it should ideally explain return values, but it doesn't, leaving gaps in completeness.

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 description coverage is 100%, meaning all parameters are well-documented in the schema itself. The description does not add any additional semantic meaning beyond what the schema provides (e.g., it doesn't explain parameter interactions or provide examples beyond the schema's descriptions). Thus, it meets the baseline score of 3 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 tool's purpose with a specific verb ('Get') and resource ('device logcat output'), and provides context about its use case ('to find crashes, exceptions, and errors after reproducing a bug'). However, it does not explicitly differentiate from sibling tools like 'clear_logs', which might handle log management differently, leaving room for improvement in sibling distinction.

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

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

The description provides clear context on when to use this tool ('after reproducing a bug'), which helps guide its application. However, it lacks explicit guidance on when not to use it or alternatives among siblings, such as distinguishing from 'clear_logs' for log clearing or other debugging tools, so it doesn't reach the highest score.

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 no annotations provided, the description carries the full burden. It discloses the return content (interactive elements with bounds, text, resource IDs, and state) and hints at a read-only operation, but lacks details on permissions, rate limits, or error handling for a tool that likely interacts with devices.

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

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

The description is front-loaded with the core purpose, followed by return details and usage guidance in two efficient sentences with zero wasted words, making it easy to parse quickly.

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

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

Given the tool's moderate complexity (device interaction, no output schema, no annotations), the description is reasonably complete by explaining what it returns and its usage context. However, it could benefit from more behavioral details like error cases or performance implications.

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

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

Schema description coverage is 100%, so the schema already documents the single optional parameter 'device_id'. The description does not add any parameter-specific information beyond what the schema provides, meeting the baseline for high 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 specific action ('Get the UI element hierarchy') and resource ('of the current screen'), distinguishing it from siblings like 'screenshot' or 'get_current_activity' by focusing on interactive elements with detailed attributes.

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

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

It provides clear context for when to use this tool ('to find elements before tapping'), which implicitly distinguishes it from direct interaction tools like 'tap' or 'tap_element'. However, it does not explicitly state when not to use it or name alternatives among siblings.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but lacks critical details: it doesn't specify permissions required (e.g., ADB access), side effects (e.g., app overwriting), error handling, or success indicators. This is inadequate for a mutation tool with zero annotation coverage.

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, direct sentence with zero wasted words. It is front-loaded with the core action and resource, making it highly efficient and easy 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?

Given the tool's complexity (installation is a mutation with potential side effects), lack of annotations, and no output schema, the description is insufficient. It doesn't explain what happens on success/failure, return values, or error conditions, leaving significant gaps for agent usage.

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 parameters ('apk_path', 'device_id') clearly documented in the schema. The description adds no additional meaning beyond the schema, such as APK validation or device selection nuances, so it meets 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 action ('Install') and resource ('an APK file on the device'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling tools like 'launch_app' or 'pull_file', but the verb 'Install' is specific enough to imply a distinct 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., device connectivity), exclusions (e.g., incompatible APK types), or related tools like 'launch_app' for post-installation actions, leaving usage context unclear.

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 no annotations provided, the description carries full burden but only states the basic action. It lacks details on behavioral traits such as whether it requires specific permissions, what happens on failure (e.g., app not installed), timeouts, or side effects (e.g., app foregrounding).

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

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

The description is a single, efficient sentence with zero waste—it directly states the tool's purpose without unnecessary words, making it front-loaded and easy 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?

Given no annotations and no output schema, the description is incomplete for a tool that performs an action like app launching. It should cover more context, such as error handling, success indicators, or dependencies on device state, to adequately guide an AI agent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds no additional meaning beyond implying 'package_name' is required, which is covered in the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the action ('Launch') and target ('Android app by package name'), providing specific verb+resource. However, it doesn't differentiate from sibling tools like 'start_emulator' or 'get_current_activity' that might involve app launching or activity 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?

No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention when to use 'launch_app' versus 'start_emulator' (for emulators) or 'get_current_activity' (for checking activity), nor does it specify prerequisites like device connection.

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 no annotations provided, the description carries full burden but only states the basic action without disclosing behavioral traits. It doesn't mention if this is a read-only operation, what format the output returns, potential errors, or any side effects like performance impact.

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 zero wasted words. It's front-loaded with the core purpose and appropriately sized for a simple tool with no parameters.

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 simplicity (0 parameters) but lack of annotations and output schema, the description is incomplete. It doesn't explain what 'available' means, the return format, or how this differs from sibling tools, leaving gaps for the agent to infer.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, earning a baseline high score since it doesn't need to compensate for schema gaps.

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 'List' and the resource 'available Android Virtual Devices', making the purpose immediately understandable. However, it doesn't differentiate from the sibling 'list_devices' tool, which appears to serve a similar function for physical devices, so it misses the highest score.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'list_devices' or 'get_device_info'. There's no mention of prerequisites, context, or exclusions, leaving the agent with minimal usage direction.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but omits critical behavioral details: whether it requires ADB connectivity, how it handles offline devices, what the output format looks like (e.g., list of device IDs, names, status), or if there are any rate limits. For a tool with zero annotation coverage, this leaves significant gaps.

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

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

The description is a single, efficient sentence that directly states the tool's purpose with zero wasted words. It is appropriately sized and front-loaded, making it immediately clear what the tool does 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?

Given the tool's low complexity (no parameters) and lack of annotations/output schema, the description is minimally adequate but incomplete. It covers the basic purpose but fails to address behavioral aspects like output format, dependencies (e.g., ADB), or error conditions. For a simple list tool, it meets the minimum viable threshold but leaves room for improvement.

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

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

The tool has zero parameters, and schema description coverage is 100% (since there are no parameters to describe). The description appropriately doesn't discuss parameters, which is correct for a parameterless tool. Baseline for zero parameters is 4, as there's no need to compensate for missing parameter documentation.

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 specific action ('List') and the target resources ('connected Android devices and emulators'). It precisely distinguishes this tool from siblings like 'list_avds' (which lists emulator definitions) or 'get_device_info' (which retrieves detailed information about a specific device).

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

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

The description implies usage context (when you need to see available Android devices/emulators), but provides no explicit guidance on when to use this tool versus alternatives like 'get_device_info' for detailed data or 'list_avds' for emulator definitions. It lacks any 'when-not-to-use' or prerequisite information.

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

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

No annotations are provided, so the description carries full burden. It mentions 'hardware/software key' but doesn't disclose behavioral traits such as whether this requires device connectivity, what happens if the key is invalid, if it's synchronous/asynchronous, or potential side effects (e.g., turning device on/off with power key). The description is too minimal for a tool that likely interacts with external systems.

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?

Extremely concise at 4 words, front-loaded with the core action. Every word earns its place, with no redundant information. However, this conciseness comes at the cost of completeness, as noted in other dimensions.

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 no annotations and no output schema, the description is incomplete for a tool with 2 parameters and likely complex behavior (interacting with devices). It doesn't cover return values, error conditions, or operational context (e.g., ADB-based), leaving significant gaps for an AI agent to understand proper 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%, with clear enum values for 'key' and optionality for 'device_id'. The description adds no parameter semantics beyond the schema—it doesn't explain key types (e.g., 'back' for navigation, 'volume_up' for audio) or device_id usage. Baseline is 3 since the schema adequately documents parameters.

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

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

The description 'Press a hardware/software key' states the action (press) and target (key), but is vague about scope and context. It doesn't specify what system or interface these keys operate on (e.g., Android device via ADB), nor does it distinguish from sibling tools like 'tap' or 'type_text' which involve different input mechanisms.

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 on when to use this tool versus alternatives. For example, it doesn't clarify when to use 'press_key' versus 'tap' (for screen coordinates) or 'type_text' (for text input), or mention prerequisites like needing a connected device. The description provides only basic function without 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?

No annotations are provided, so the description carries full burden. It states the action but lacks behavioral details: it doesn't specify if it overwrites existing local files, handles errors (e.g., missing remote file), requires ADB setup, or has performance implications like timeouts. This is a significant gap for a tool with potential 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, efficient sentence that directly states the tool's purpose with zero waste. It's front-loaded and appropriately sized for a straightforward operation, making it easy to parse quickly.

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

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

Given no annotations and no output schema, the description is incomplete for a tool that performs file operations with potential side effects. It lacks details on error handling, permissions, or what happens on success/failure, which are crucial for an agent to use it correctly in context with other ADB-related tools.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (remote_path, local_path, device_id) with clear descriptions. The description adds no additional meaning beyond implying the tool uses these parameters, meeting the baseline for high schema coverage without extra value.

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

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

The description clearly states the action ('pull') and resource ('a file from the Android device'), specifying both source and destination. It distinguishes itself from siblings like 'screenshot' or 'get_logs' by focusing on file transfer, though it doesn't explicitly differentiate from similar file operations if they existed.

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 on when to use this tool versus alternatives. While the context implies it's for file transfer from an Android device, there's no mention of prerequisites (e.g., device connectivity), exclusions (e.g., not for pulling directories), or comparisons to other tools like 'adb_shell' for more complex operations.

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 no annotations provided, the description carries full burden. It discloses that the tool returns an image for analysis and optionally saves to a file, which are useful behavioral traits. However, it lacks details on permissions needed, potential side effects (e.g., screen interruption), or error handling, leaving gaps for a mutation tool.

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

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

The description is extremely concise with two sentences that directly state the action, return value, and optional feature. Every word earns its place, and it is front-loaded with the core purpose, making it efficient and easy 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?

Given the tool's moderate complexity (capturing screenshots with optional saving), no annotations, and no output schema, the description is minimally adequate. It covers the basic operation and return, but lacks details on output format (e.g., image type, size), error cases, or dependencies, leaving room for improvement.

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 both parameters (device_id and save_path) with their descriptions. The description adds no additional meaning beyond what the schema provides, such as clarifying the optional nature or usage context, meeting the baseline for high 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 specific action ('Take a screenshot') and target resource ('of the Android device'), distinguishing it from all sibling tools which perform different operations like shell commands, app management, or UI interactions. It precisely identifies the tool's unique function in the context.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., device connectivity), scenarios where screenshotting is appropriate, or how it differs from other visual tools like get_ui_tree. Usage is implied but not explicitly stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'repeatedly' and 'until visible,' hinting at iterative behavior, but lacks details on error handling, timeouts, scroll direction, or what happens if the element is not found after max_scrolls. This leaves gaps for a tool with potential 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, efficient sentence with zero waste—every word contributes to understanding the tool's purpose. It is front-loaded with the core action and condition, making it easy to grasp quickly 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?

Given no annotations and no output schema, the description adequately covers the basic purpose but lacks details on behavioral outcomes, error cases, or return values. For a tool with 4 parameters and potential iterative operations, more context on failure modes or success criteria would improve completeness.

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 thoroughly. The description adds no additional meaning beyond implying that 'by' and 'value' define the 'criteria' for matching, but it does not explain parameter interactions or usage nuances, meeting 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 specific action ('scroll down repeatedly') and target ('until an element matching the given criteria is visible'), distinguishing it from siblings like tap_element or wait_for_element that involve different interactions. It uses precise verbs and defines the resource scope effectively.

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

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

The description implies usage when an element is not immediately visible and requires scrolling to locate it, providing clear context. However, it does not explicitly state when not to use this tool or name alternatives like tap_element or wait_for_element, which could offer more direct 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?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it starts an emulator and waits up to 60 seconds for it to come online, which is crucial for timing and automation. However, it lacks details on error handling, permissions, or what happens if the emulator fails to start within the timeout.

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 extremely concise and front-loaded, consisting of just two sentences that directly state the tool's purpose and key behavior. Every word earns its place, with no redundant or vague language.

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 moderate complexity (starting an emulator with a timeout), no annotations, and no output schema, the description is minimally adequate. It covers the core action and timing but lacks information on return values, error conditions, or dependencies, leaving gaps for an AI agent to infer.

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

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

The input schema has 100% description coverage, with 'avd_name' clearly documented as 'Name of the AVD to start (from list_avds)'. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline of 3 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 specific action ('Start an Android emulator') and the resource ('AVD'), distinguishing it from siblings like 'list_avds' (which lists emulators) or 'list_devices' (which lists connected devices). It explicitly mentions the waiting behavior, which is unique to this tool.

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

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

The description implies usage by referencing 'avd_name' from 'list_avds', suggesting this tool should be used after listing available AVDs. However, it does not explicitly state when to use this tool versus alternatives like 'adb_shell' for direct commands or provide clear exclusions (e.g., not for physical devices).

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 no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the action but fails to explain critical traits: whether this requires a connected device, if it's destructive (e.g., could trigger unintended actions), what happens on failure, or any rate limits. This leaves the agent guessing about operational risks and constraints.

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

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

The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core action, making it easy to parse quickly, and every part of the sentence contributes essential information, earning its place.

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

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

Given the complexity of a screen interaction tool with no annotations and no output schema, the description is insufficient. It doesn't cover behavioral aspects (e.g., safety, prerequisites), usage context relative to siblings, or result expectations (e.g., success/failure indicators). For a tool that could have side effects, this leaves significant gaps in understanding.

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 description coverage is 100%, with clear documentation for all parameters (coordinates, duration, device ID). The description adds no additional meaning beyond the schema, such as explaining coordinate systems (e.g., pixel-based, relative), typical duration values, or device ID usage. Baseline 3 is appropriate as the schema does the heavy lifting, but the description doesn't enhance understanding.

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 ('perform a swipe gesture') and the target ('on the screen'), which is specific and unambiguous. However, it doesn't distinguish this tool from potential alternatives like 'scroll_to_element' or 'tap', which are also screen interaction tools in the sibling list, leaving room for confusion about when to choose swipe over those.

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 no guidance on when to use this tool versus alternatives like 'tap', 'scroll_to_element', or 'press_key' from the sibling list. It lacks context about typical use cases (e.g., navigating, scrolling) or prerequisites (e.g., needing a device connected), offering only a basic statement of function without practical application advice.

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 no annotations provided, the description carries the full burden of behavioral disclosure. While 'Tap' implies a user interaction action, the description doesn't specify what happens after the tap (e.g., does it wait for UI response?), whether it requires device connectivity, or any error conditions. This is inadequate for a tool that performs device interaction.

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 extremely concise at just 4 words, front-loading the core functionality with zero wasted words. Every element ('Tap', 'at specific screen coordinates') directly contributes to understanding the tool's 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 device interaction tool with no annotations and no output schema, the description is insufficient. It doesn't explain what constitutes successful execution, what errors might occur, or how this differs from similar tapping tools in the sibling set. The agent lacks critical context for proper tool 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%, with all parameters clearly documented in the schema. The description adds no additional parameter semantics beyond what's already in the schema, so it meets the baseline expectation without providing extra value.

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

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

The description clearly states the action ('Tap') and target ('at specific screen coordinates'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from sibling tools like 'tap_element' or 'tap_and_wait', which appear to serve similar tapping functions but with different approaches.

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 no guidance on when to use this tool versus alternatives like 'tap_element' or 'tap_and_wait'. There's no mention of prerequisites, use cases, or exclusions, leaving the agent with no contextual direction for tool selection.

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 no annotations provided, the description carries full burden. It discloses the behavioral trait of returning 'the new UI tree' after the operation, which is valuable. However, it doesn't mention potential side effects (like what happens if the tap fails), error conditions, or performance characteristics beyond 'fast operation'. For a tool with no annotations, this leaves some behavioral aspects unclear.

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 perfectly concise with two sentences that each earn their place: the first states the core functionality, and the second explains the efficiency benefit. It's front-loaded with the main purpose and contains zero 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 tool with 4 parameters, 100% schema coverage, but no output schema and no annotations, the description does well by explaining the composite nature and efficiency benefit. However, it doesn't describe the return value format (what 'UI tree' means) or error scenarios, leaving some gaps given the lack of 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%, so the schema already fully documents all parameters. The description doesn't add any parameter-specific information beyond what's in the schema (like explaining the 'by' enum values or 'wait_ms' behavior). With complete schema coverage, the baseline score of 3 is appropriate as the description doesn't enhance parameter understanding.

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 specific action ('Tap element then wait for UI to settle and return the new UI tree') and explicitly distinguishes it from sibling tools by mentioning it combines 'tap + wait + get_ui_tree into a single fast operation'. This directly contrasts with individual tools like 'tap', 'wait_for_element', and 'get_ui_tree' in the sibling list.

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 guidance on when to use this tool versus alternatives: it states it's for combining three operations (tap, wait, get_ui_tree) into one faster operation, implying it should be used instead of calling those three tools separately. This gives clear context about its efficiency advantage over the 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the action (tap) and finding mechanism, but lacks details on permissions needed, error handling (e.g., if element not found), side effects (e.g., UI changes), or performance aspects. This is a significant gap for a tool that interacts with UI elements.

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 that front-load the core action and mechanism, with no wasted words. Every sentence earns its place by specifying the tool's purpose and behavior efficiently.

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

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

Given no annotations and no output schema, the description is minimal but covers the basic action. However, for a tool with 3 parameters and UI interaction complexity, it lacks details on return values, error cases, or behavioral nuances, making it adequate but with clear gaps in completeness.

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 ('by', 'value', 'device_id') with descriptions and enums. The description adds no additional meaning beyond what the schema provides, such as examples or usage context for the parameters, meeting 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 specific action ('tap a UI element') and the mechanism ('by its resource-id, text, or content-desc'), distinguishing it from siblings like 'tap' (which lacks the same specificity) and 'tap_and_wait' (which implies additional waiting behavior). It precisely defines the verb and resource with implementation details.

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

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

The description implies usage by stating it 'finds the element in the UI tree and taps its center,' suggesting it's for interacting with visible UI elements. However, it lacks explicit guidance on when to use this tool versus alternatives like 'tap' (which might be simpler) or 'tap_and_wait' (for asynchronous interactions), and doesn't mention 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the basic action but doesn't mention important behavioral aspects: whether this simulates keyboard input or direct text injection, potential timing/rate limitations, error conditions (e.g., if no field is focused), or what happens after typing (e.g., whether focus remains).

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

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

The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a simple tool and front-loads the essential information immediately.

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

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

For a relatively simple tool with good schema coverage but no annotations or output schema, the description provides the basic purpose but lacks important context. It doesn't explain what constitutes a 'currently focused input field' in the Android context, nor does it describe potential side effects or error conditions that would help an agent use it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action ('type text') and target ('currently focused input field'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from potential alternatives like 'tap' or 'tap_element' that might also input text through different mechanisms.

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 no guidance about when to use this tool versus alternatives like 'tap_element' or 'press_key' for text input. It doesn't mention prerequisites (e.g., requiring a focused input field) or exclusions (e.g., not working on non-input elements).

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 no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about polling behavior ('Polls every 500ms'), which isn't in the schema, but doesn't cover other aspects like error handling, what happens on timeout, or performance implications.

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 extremely concise and front-loaded with the core purpose in the first sentence and operational detail in the second. Every sentence earns its place 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?

Given no annotations and no output schema, the description is minimal but covers the basic operation. For a tool with 4 parameters and behavioral complexity (polling, timeout), it should ideally explain more about return values or failure modes, but it's adequate for the core functionality.

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 thoroughly. The description adds no additional parameter semantics beyond what's in the schema, maintaining the baseline score of 3.

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

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

The description clearly states the tool's purpose: 'Wait for a UI element to appear on screen.' It specifies the verb ('wait for') and resource ('UI element'), though it doesn't explicitly differentiate from siblings like 'tap_and_wait' or 'scroll_to_element' beyond the polling behavior mentioned.

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 no guidance on when to use this tool versus alternatives. It mentions polling every 500ms but doesn't specify scenarios where this is preferred over other UI interaction tools or prerequisites for usage.

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