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 effectively describes key behavioral traits: reliability advantages over keyboard_type, how 'narrate' parameter affects confirmation behavior, safety guards when using 'lensId', and limitations regarding element types. It doesn't mention error handling or performance characteristics, but covers most critical operational aspects.

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 efficiently structured with zero wasted sentences. It front-loads the core purpose, then provides usage guidance, parameter context, and limitations in a logical flow. Each sentence adds distinct value: reliability comparison, narration usage, safety guard explanation, and caveats about element compatibility.

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 6 parameters, no annotations, and no output schema, the description provides substantial context about behavior, limitations, and parameter usage. It covers the tool's purpose, when to use it vs alternatives, behavioral characteristics, and parameter semantics. The main gap is lack of information about return values or error conditions, but given the rich parameter guidance and behavioral transparency, it's mostly 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?

With 100% schema description coverage, the baseline is 3. The description adds meaningful context beyond the schema: it explains the purpose of 'narrate' parameter ('to confirm the value was applied without a verification screenshot'), clarifies the role of 'lensId' ('to run safety guards... and receive post.perception state feedback'), and provides caveats about which elements work with this method. This adds significant practical 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 tool's purpose: 'Set the value of a text field or combo box via UIA ValuePattern.' It distinguishes from sibling tools like 'keyboard_type' by specifying it's 'more reliable than keyboard_type for programmatic form input' and explicitly mentions when to use alternatives ('does not work on contenteditable HTML or custom rich-text editors — use keyboard_type for 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 explicit usage guidelines: it states when to use this tool ('more reliable than keyboard_type for programmatic form input'), when not to use it ('Only works for elements that expose ValuePattern; does not work on contenteditable HTML or custom rich-text editors'), and names the alternative tool ('use keyboard_type for those'). It also includes guidance on optional parameters like 'narrate' and 'lensId'.

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