nvda-mcp server

Overview Schema Source Related Servers Discussions Admin

Trace NVDA events

nvda_trace_events

Records NVDA events (focus, name, value, live region, UIA notifications) and the speech it produced while handling them, then reports results so you can diagnose why NVDA said nothing.

Instructions

Record the events NVDA handles (focus changes, name and value changes, live regions, UIA notifications...) and what NVDA said while handling each one.

This answers "why did NVDA say nothing?": either the application sent no event, or NVDA got one and chose not to speak. Start tracing, act (nvda_press_keys or the user), then read. With background_window it also shows whether an add-on could follow a window it is not in, such as new messages in a chat. Tracing stops by itself after 10 minutes.

Input Schema

Name	Required	Description	Default
`app`	No	With start: only record events from this application, such as 'mwmod'.
`tree`	No	With start: also read the accessibility tree of the foreground window (its web document in browsers, or background_window), so stop says what changed in it: controls added, removed, renamed or moved, values and states. Use it for something the user does, or several actions.
`limit`	No	Return at most this many of the newest events.
`action`	Yes	'start' begins recording; 'read' returns what was recorded and keeps going; 'stop' returns it and stops.
`events`	No	With start: only record these events, such as ['gainFocus', 'nameChange', 'valueChange', 'liveRegionChange', 'UIA_notification']. All events by default.
`wait_ms`	No	With read or stop: keep recording this long first, for example while the user tries something.
`after_id`	No	With read or stop: only events after this id (afterId from start, or lastId).
`max_changes`	No	With stop and tree: list at most this many tree changes.
`tree_within`	No	With start: read only the tree inside this control, an id from nvda_find_objects. Implies tree.
`ignore_pattern`	No	With stop and tree: a regular expression for text that changes by itself, such as times, ignored when comparing.
`response_format`	No	'markdown' (default) is easier to read; 'json' keeps every field for further processing.	markdown
`background_window`	No	With start: also ask NVDA for events from this window while it is in the background, a handle from nvda_list_windows, as an add-on can with eventHandler.requestEvents. NVDA normally ignores most of them. They are recorded with the control's value and the text of live regions, but NVDA does not act on them.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.0Nov 5, 2026

TDQS

A4.2/5.0

Behavior3/5

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

The annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) already signal a stateful, non-idempotent session tool. The description adds genuinely useful behavior beyond that: tracing stops by itself after 10 minutes, and background_window events are recorded but NVDA does not act on them. It does not, however, say whether concurrent traces are allowed or what happens if start is called while a trace is already running.

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?

It is short and front-loaded: what is recorded first, then the diagnostic question it answers, then the start/act/read loop, then the timeout. The background_window sentence is dense and slightly awkwardly hung off the end, but every sentence contributes.

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 12-parameter stateful tool this is complete: an output schema exists so return values need no explanation, and the description covers the lifecycle (start/read/stop), the auto-stop timeout, and the two optional capture modes. An agent has enough to call it correctly on the first attempt.

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

Parameters3/5

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

Schema description coverage is 100% and every parameter already carries a detailed, usage-scoped description (app, tree, events, wait_ms, after_id, tree_within, ignore_pattern, background_window). The prose adds workflow context but no parameter meaning that the schema does not already state, so baseline 3 applies.

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?

The description states a specific verb and resource: record the events NVDA handles (focus changes, name and value changes, live regions, UIA notifications) plus what NVDA said while handling them. It frames the diagnostic question it answers ('why did NVDA say nothing?'), which separates it from nvda_get_speech_history (what was spoken) and nvda_get_log (general logging).

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?

It gives an explicit procedure: start tracing, act (via nvda_press_keys or the user), then read. It also names the condition for the tree variant (something the user does, or several actions) and the background_window variant (whether an add-on could follow a window it is not in, e.g. chat messages). Sibling tools nvda_press_keys, nvda_find_objects and nvda_list_windows are referenced by the parameters they feed.

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