qtpy-mcp

Overview Schema Source Related Servers Discussions Admin

qt_batch

Executes multiple Qt widget actions—clicks, typing, key presses, waits, and snapshots—in a single round trip to cut latency from sequential calls. Stops on the first error and returns partial results.

Instructions

Execute multiple Qt operations in a single round trip.

Chains clicks, types, key presses, waits, snapshots, and reads into one server call — dramatically reduces latency compared to sequential tool calls.

Each step dict: method (str, required): RPC method — same names as probe methods: click, type_text, key_press, set_property, invoke_slot, get_text, trigger_action, wait_for, snapshot, find_widget, screenshot. Special: "wait" with params {"ms": N} sleeps N ms processing events. params (dict, optional): Parameters forwarded to the method. wait_ms (int, optional): Extra pause after the step (default 0).

Execution stops on the first error; partial results are returned. Screenshot steps return size only (not base64 data) — call qt_screenshot separately when you actually need the image.

Note: refs must be known before calling qt_batch — steps cannot reference results from earlier steps within the same batch. Use qt_find_widget first to obtain refs, then pass them into the batch call.

Example — click a button twice then read a label in one round trip: qt_batch([ {"method": "click", "params": {"ref": "w5"}}, {"method": "click", "params": {"ref": "w5"}}, {"method": "get_text", "params": {"ref": "w12"}}, ])

Example — type multi-line code into IPython console and wait for output: qt_batch([ {"method": "type_text", "params": {"ref": "w42", "text": "%run /tmp/x.py", "use_clipboard": true}}, {"method": "key_press", "params": {"key": "Return"}}, {"method": "wait", "params": {"ms": 3000}}, {"method": "snapshot", "params": {"max_depth": 4}}, ])

Input Schema

Name	Required	Description	Default
`steps`	Yes
`instance`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 23, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses failure semantics ('execution stops on the first error; partial results are returned'), output truncation for screenshot steps (size only, not base64), the default for wait_ms, and the 'wait' special-case that processes events during sleep. The no-forward-reference constraint between steps is exactly the kind of non-obvious behavior an agent would otherwise discover by failing.

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

Conciseness4/5

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

Front-loaded with the one-line purpose, then a spec block, then caveats, then examples — good ordering with no filler. The two examples are long but demonstrate distinct non-obvious patterns (ref reuse and clipboard-based typing plus wait), so they mostly earn their space; the second could be trimmed slightly.

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

Completeness5/5

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

An output schema exists, so return values needn't be described, and everything else an agent needs to call this correctly is present: sub-object schema, method vocabulary, error/partial-result behavior, prerequisite for refs, and the screenshot caveat. The only omission is the instance selector, which sibling qt_select_instance handles.

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

Parameters4/5

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

Schema description coverage is 0% and the steps array is a free-form object with additionalProperties, so the schema documents nothing — the description compensates by fully specifying the sub-object keys (method required, params optional, wait_ms default 0) and enumerating valid method names plus the 'wait' special form. The remaining gap is the top-level 'instance' parameter, which is never mentioned.

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

Purpose5/5

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

States a specific verb and resource — executing multiple Qt operations in one round trip — and immediately enumerates the step types it chains (clicks, types, key presses, waits, snapshots, reads). It explicitly distinguishes itself from siblings by naming qt_screenshot and qt_find_widget as the tools to use when you need the image or the refs.

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

Usage Guidelines5/5

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

Gives the condition that selects this tool ('dramatically reduces latency compared to sequential tool calls') and the prerequisite that gates it ('refs must be known before calling qt_batch ... use qt_find_widget first'). It also routes the agent away to qt_screenshot when actual image data is needed, which is the classic misuse case.

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