qtpy-mcp

Overview Schema Source Related Servers Discussions Admin

qt_screenshot

Captures a Qt window or widget identified by ref or semantic description, returning an image with optional downscaling and PNG/JPEG format.

Instructions

Take a screenshot of a window or any widget, identified by ref OR by description.

Identify the widget semantically instead of by ref, e.g. describe="Name goes here:" (a label: captures the widget that holds it), describe="save the profile" (tooltip), window_title="PIPE-1234" with class_name="QDockWidget" (a docked widget), or object_name="nameEdit". Add instance (pid, id or window title of the app) when several Qt apps are running.

Args: ref: Widget ref from qt_snapshot/qt_find_widget. If nothing identifies a widget, the active window is captured. full_window: If True, captures the first visible top-level window. max_width: Max width before downscaling (default 1920). max_height: Max height before downscaling (default 1080). format: Image format - 'png' or 'jpeg' (default 'png'). quality: JPEG quality 1-100 (default 80, ignored for PNG). describe: Free-text description matched against text, titles, tooltip, what's-this, status tip, accessible name, objectName, placeholder, QSS ... (fuzzy). window_title: Fuzzy match on the top-level window title. class_name: Qt class, subclasses match (e.g. 'QDockWidget'). object_name: objectName, supports * and ? wildcards. search_fields: Limit describe to specific fields (see qt_find_widget). expand: What to capture relative to the match: 'auto' (a matched label captures the widget holding it; anything else captures itself), 'self', 'parent', 'buddy' (the label's field) or 'window'. index: Which ranked match to use (0 = best). min_score: Minimum semantic match score 0-1.

Returns an image plus a note saying what was captured.

Input Schema

Name	Required	Default
`ref`	No
`index`	No
`expand`	No	auto
`format`	No	png
`quality`	No
`describe`	No
`instance`	No
`max_width`	No
`min_score`	No
`class_name`	No
`max_height`	No
`full_window`	No
`object_name`	No
`window_title`	No
`search_fields`	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.3/5.0

Behavior4/5

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

With no annotations, the description carries the burden and does well: it documents downscaling caps, JPEG quality being ignored for PNG, fuzzy matching behavior, wildcard support, and that the return is an image plus a note describing what was captured. Missing only mutation/side-effect framing (none expected) and any note on capture cost or failure modes when no widget matches.

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 core action and a compact set of worked examples, then a clean Args list; minimal waste. The four inline examples are slightly verbose but each illustrates a distinct identification strategy, so they earn their space.

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?

For a 15-parameter, zero-annotation tool with an output schema, the description covers targeting modes, defaults, downscaling, and the fallback path. Return-value detail is not required given the output schema, and the brief 'returns an image plus a note' is sufficient orientation.

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

Parameters5/5

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

Schema description coverage is 0%, yet the Args block documents essentially all 15 parameters, including non-obvious ones: `expand`'s four modes and its 'auto' label-captures-holder rule, `index` as ranked-match selector, `min_score` range, and `search_fields` delegation to qt_find_widget. `instance` is explained in the prose preamble rather than the Args list, but is still covered.

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

Purpose4/5

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

The opening sentence gives a specific verb (take a screenshot) and resource (a window or any widget), plus the two identification modes (ref vs. description). It does not explicitly contrast itself with near-neighbours like qt_vtk_screenshot or qt_scene_snapshot, so the agent must infer which screenshot tool to pick.

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

Usage Guidelines4/5

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

It spells out how to select a target: ref from qt_snapshot/qt_find_widget, semantic `describe` with concrete examples, window_title+class_name, object_name, and `instance` when multiple Qt apps run, plus the fallback that the active window is captured when nothing identifies a widget. It gives no explicit when-not or alternative-tool routing against the other capture tools.

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