desktop-touch-mcp

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 thoroughly describes behavioral traits, including what data is returned (e.g., 'focusedWindow (title, hwnd), focusedElement (name, type, value)'), limitations (e.g., 'Cannot detect non-UIA elements (custom-drawn UIs, game overlays)'), platform-specific behavior (e.g., 'Chromium: cursorOverElement is null (UIA sparse)'), and performance considerations (e.g., 'far cheaper than any screenshot'). This goes beyond any structured fields to provide rich context for the agent.

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 with sections like 'Purpose,' 'Details,' 'Prefer,' and 'Caveats,' making it easy to parse. It is appropriately sized, with each sentence adding value, such as explaining use cases, limitations, and alternatives. While not minimal, it avoids waste and is front-loaded with key 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 complexity of the tool (querying multiple UI states) and the absence of annotations and output schema, the description provides complete context. It details the return values, performance benefits, usage scenarios, limitations, and sibling tool distinctions, ensuring the agent has all necessary information to invoke the tool correctly without relying on structured output fields.

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 information is needed in the description. The baseline for 0 parameters is 4, as the description does not need to compensate for any gaps. It appropriately focuses on output semantics and usage without redundant parameter details.

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 explicitly states the tool's purpose as querying 'focused window, focused element, cursor position, and page state in one call,' distinguishing it from screenshot or get_ui_elements. It uses specific verbs like 'query' and 'confirm' and clearly identifies the resource as UI state elements, making it distinct from siblings like get_cursor_position or get_active_window.

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 (e.g., 'Use after keyboard_type or set_element_value to confirm the value landed in the expected field' and 'Use instead of screenshot(detail='meta') when the question is only which window/control has focus') and when not to use it (e.g., 'Does NOT enumerate descendants — use screenshot(detail='text') or get_ui_elements for the full clickable element list'). It names alternatives and specifies contexts, offering comprehensive usage instructions.

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