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

Annotations already declare destructiveHint=true, openWorldHint=true, non-idempotent and not read-only, so the safety profile is covered. The description adds that it reports what NVDA said afterward and that the control need not be focused, but it does not warn that the action may be irreversible, which is the main risk for a destructive hint.

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?

Two short sentences, front-loaded with the action and examples, then the prerequisite. Nothing is padded or repetitive, and the key constraint (no focus needed) lands before the reader stops paying attention.

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?

With annotations, a fully documented six-parameter schema and an output schema present, the description only needs to convey purpose, prerequisite and result behavior, which it does. The only shortfall is the absence of any note on the real-world side effects of activation, which matters for a destructive-hinted tool.

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?

Schema description coverage is 100%, with rich per-parameter text covering record, settle_ms, timeout_ms, until_speech and record_within, so the schema does the heavy lifting. The description adds no further parameter meaning, which matches the baseline of 3 when the schema is complete.

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?

Uses a specific verb ('Perform a control's default action') plus concrete examples (press a button, follow a link, toggle a check box) and names the source of the target (nvda_find_objects). It implicitly separates itself from nvda_focus_object by saying focus is not required, but it never names the sibling it is not.

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?

Gives a clear prerequisite (the id comes from nvda_find_objects) and a useful condition (no need to focus first), which is implied usage guidance. It does not say when to prefer this over nvda_press_keys, nvda_set_value, or a focus-then-activate sequence, leaving real alternatives unaddressed.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true; the description's "counts as controlling the computer" is consistent with that rather than contradicting it. It adds behavior the annotations don't convey: minimized windows are restored, multiple matches resolve to the first in nvda_list_windows order with the rest reported, and speech plus new focus are captured. It does not explain why the call would be destructive or whether anything is closed.

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?

Three short sentences: behavior and return, selector rules and tie-breaking, then the control-action warning. The action is front-loaded and no sentence is redundant.

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?

With 0 required parameters, a 100% documented schema and an output schema covering return values, the remaining burden is selection logic and side-effect disclosure, both of which are present. The only omission — relative choice versus nvda_activate_object — is minor given the tool's self-contained specification.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the schema marks all five parameters optional, and "Pass title_contains or handle" tells the agent that one of these two selectors is effectively mandatory. It also names nvda_list_windows as the source of handle values, which the schema only implies.

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?

"Bring a window to the front, restoring it if minimized, then report what NVDA said and the new focus" is a specific verb plus resource, and it adds the observable outcome. It doesn't explicitly contrast with nvda_activate_object or nvda_focus_object, which are the nearest siblings and differ only by window-vs-object scope, so an agent must infer that distinction.

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?

"Pass title_contains or handle" plus "If several titles match, the first in nvda_list_windows order wins and the others are listed" gives concrete preconditions and a deterministic resolution rule. The caution that it "counts as controlling the computer, like nvda_press_keys" signals real side effects. It still never states when to prefer this over nvda_activate_object or nvda_focus_object, so no explicit exclusion exists.

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

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

Annotations already declare non-read-only, non-idempotent, open-world and destructive behavior, and the description reinforces why: it presses a key repeatedly, enumerates the termination conditions (focus returns to start, stops moving, leaves the app), and warns that focus is left wherever the walk ends. That side-effect disclosure is the valuable addition; what remains unstated is whether the walk can be interrupted or undone.

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?

Front-loads the purpose, then the mechanism, then stopping rules and flagged issues, then prerequisites. Sizing is appropriate for a multi-behavior tool, though the list of flagged problem classes is long enough to be slightly dense.

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?

An output schema exists, so return values need not be described, and the description still covers prerequisites, stopping behavior and side effects. What is thin is the meaning of the 'key presses allowed' prerequisite and any guidance on what to do with the reported findings.

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?

Schema coverage is 100%, with default, bounds and format guidance already on each parameter. The description only loosely echoes the key-pressing role of `key` and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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?

States a specific verb and resource (walk keyboard focus order, report accessibility problems) plus the mechanism (what NVDA actually announces). This is clearly distinguishable from siblings like nvda_press_keys or nvda_get_object_tree, which do not audit or flag issues.

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?

Gives a concrete pre-call condition (ask the user to focus the first control of the window to audit) and a capability prerequisite (key presses must be allowed, like nvda_press_keys). It does not explicitly say when to prefer this over alternatives such as nvda_list_elements or nvda_get_object_tree, so it falls short of full alternative routing.

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

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

Beyond the readOnly/idempotent/non-destructive annotations the description discloses the crucial operational traits: a client setting must be enabled, it is off by default because the image is sent to the AI provider, the target window must be in front since the capture is positional, and it works with Screen Curtain on. That is exactly the context an agent needs before invoking and reporting results.

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?

Two short paragraphs, front-loaded with purpose and use cases, followed by prerequisites and side-effect warnings. Every sentence carries information; only the closing 'It works with NVDA's Screen Curtain on' is a minor afterthought rather than essential routing 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?

There is no output schema, so the description must explain what comes back - and it does: a picture of the screen at the control's position plus what NVDA says for it. Combined with prerequisite and privacy caveats, nothing an agent needs to call this correctly and interpret the result is missing.

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?

Schema description coverage is 100% and all three parameters (id, target, padding) are documented with defaults and constraints, so the schema already carries the parameter burden. The description only implicitly touches parameters through 'at the control's position' and adds no syntax, format, or interaction detail beyond the schema - baseline 3 applies.

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 states a specific verb and resource - capture a picture of a control as it appears on screen together with NVDA's speech for it - and frames the comparison between the two. It is clearly distinct from sibling read tools like nvda_inspect_object or nvda_get_speech_history, which return structured data rather than a screenshot-plus-announcement pair.

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?

Usage is spelled out concretely: find icon-only buttons announced without a useful name, visible text missing from the accessible name (WCAG 2.5.3), and controls that look like one thing but are announced as another, plus the note that it helps when the developer cannot see the screen. It stops short of naming an explicit alternative (e.g. 'if you only need the accessible name, use nvda_inspect_object'), so no exclusions are given.

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

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

The key operational prerequisite is disclosed: results come 'through the browser's remote debugging', so a browser must be launched with debugging enabled. The description also defers to nvda_inspect_html for cautions, which is useful shorthand but not self-contained. It says nothing about failure behavior when debugging is off or no page is loaded, and the readOnlyHint=false / idempotentHint=false annotations arguably sit oddly with a pure lookup, without the text clarifying why.

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?

Two short paragraphs, front-loaded with the purpose and a concrete example, with no wasted phrasing. Minor blemishes: a stray closing quotation mark and the second paragraph being a bare cross-reference rather than an integrated clarification.

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?

An output schema exists, so return values need no explanation, and the description still summarizes the shape (tag, attributes, text). For a five-parameter, fully documented developer tool this is largely complete; only the boundary with nvda_inspect_html and the remote-debugging setup path are left implicit.

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?

Schema description coverage is 100%, so the schema already documents port, within, selector, max_results and response_format thoroughly. The description reinforces the selector-based searching and the '(or inside a control)' scope that maps to within, but adds no format, syntax or default guidance beyond the schema.

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 gives a specific verb and resource: find elements in the page NVDA is reading (or inside a control) by CSS selector, returning tag, attributes and text. It is clearly a developer-facing DOM query tool. It does not, however, state how it differs from the near-named sibling nvda_inspect_html or from nvda_find_in_page, so the agent must infer the boundary.

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?

It supplies a use case — seeing how an app marks elements (e.g. WhatsApp's data-icon attributes) that NVDA cannot see — and restricts the audience to add-on developers. But it never says when to choose this over nvda_inspect_html, nvda_find_in_page or nvda_find_objects, which is the main routing decision an agent faces here.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false, openWorldHint=true, and the description is consistent with that by disclosing that the cursor moves and the match is spoken. Beyond the annotations it adds the dialog-free behavior, the browse-mode prerequisite, and the F3 continuation. It does not say what happens when no match is found, which keeps it below 5.

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?

Two short paragraphs, front-loaded with the core action, then the prerequisite and alternative. Every sentence carries information; nothing is redundant.

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 six-parameter tool with full schema coverage and an output schema, the description supplies exactly the missing pieces: the state-changing cursor behavior, the browse-mode requirement, and the routing to a safer sibling. Nothing an agent needs to call it correctly is absent.

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?

Schema description coverage is 100%, so text, reverse, from_start, case_sensitive, settle_ms and timeout_ms are all already documented in the schema. The description adds no extra semantics on direction, case handling, or timing bounds, so baseline 3 applies.

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?

States a specific verb and resource: move NVDA's browse-mode cursor to the next match and read that line, plus the analogue NVDA+control+f. It also distinguishes itself from the nearest sibling by naming nvda_get_text with contains as the non-moving alternative.

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?

Gives an explicit prerequisite (a web page or document in browse mode) and an explicit alternative path (nvda_get_text with contains) for the case where the cursor should not move. It also tells the agent how to continue the search afterwards via NVDA+F3.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), and the description adds genuinely new behavior: result ordering, cross-window/other-virtual-desktop reach, and crucially the id lifetime contract ('Ids stay valid through later searches, until the control disappears'). It omits what a zero-match or truncated search returns, which is the main remaining behavioral gap.

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?

Four short sentences, front-loaded with the core action, then the returned id contract, then the efficiency argument, then the narrowing tip. No filler and no restatement of the title.

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?

An output schema exists, so return-value detail is rightly omitted, and the description covers discovery, scoping, and id reuse across the follow-up tools (nvda_focus_object, nvda_activate_object, nvda_inspect_object). What is missing is failure/empty-result behavior and any hint about how ordering interacts with max_results when results are capped.

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?

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning by explaining the two-step pattern for 'within' (locate a container first, then narrow) and the top-down ordering that governs how 'max_results' truncates. 'role' and 'name_contains' get no semantics beyond the schema, capping this below 5.

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?

States a specific verb and resource ('Search ... for controls by name and/or role') plus the scope ('foreground window, or another window'). It also gives result ordering ('nearest the top of the window first'), which separates it from tree-dumping siblings like nvda_get_object_tree or nvda_list_elements without the agent needing to open their schemas.

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?

Explicitly positions the tool against alternatives ('Faster and more precise than reading the whole tree or tabbing around') and gives a concrete narrowing workflow: find a container with role 'list'/'dialog'/'section' and pass its id as within. It does not name the sibling tools it replaces, nor state when a full-tree read or nvda_find_in_page would be better, so it stops short of full when/when-not routing.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is carried by structured data; the description does not contradict it. It adds genuine context beyond the annotations: focus may be refused for some controls, and the call reports what NVDA spoke afterward. It does not address why the operation is flagged destructive or what state changes a focus move can cause.

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?

Two short sentences, front-loaded with the action and its outcome, followed by the workflow hint and the failure caveat. Nothing is repeated from the schema or annotations and no sentence is wasted.

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?

An output schema exists, so the description need not explain return values, and the stated 'report what NVDA said' is consistent with it. For a 6-parameter mutation tool it covers the prerequisite, the follow-on tool, and the main failure mode. Only a note on interaction with nvda_activate_object or on what the destructive hint implies is missing.

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?

Schema description coverage is 100%, so every parameter (id, record, settle_ms, timeout_ms, until_speech, record_within) is already documented, and the description adds only the notion that id originates from nvda_find_objects, which the schema already states. No added semantics such as how until_speech interacts with settle_ms are supplied. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a concrete verb and resource ("Move keyboard focus to a control") and ties the target to nvda_find_objects, which is how the required id is obtained. It also names the forward chaining sibling (nvda_type_text), so an agent can place it in a workflow. It stops short of distinguishing itself from nvda_activate_object, the other sibling that acts on an object id.

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?

"Use this to reach an edit field before nvda_type_text" gives explicit when-to-use guidance and a clear ordering relative to another tool. The caveat "Some controls cannot take focus" warns of a failure mode. No explicit when-not-to-use or statement of which alternative to pick when focusing fails (e.g. nvda_activate_object), which keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description's added value is describing what the log contains (key presses, typed text, window switches, control activations) and that entries carry time and window context, but it says nothing about retention, ordering guarantees, or whether the log is truncated.

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?

It is a single well-formed sentence with the core purpose front-loaded and no filler. The trailing colon-list of event types is slightly dense but each item carries real information about what the log records.

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?

An output schema exists, so the description need not explain return values, and it still usefully characterizes the entry content and recency ordering. For a one-parameter read-only tool with full annotation coverage, the remaining gap is the lack of differentiation from other log/history tools.

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?

Schema description coverage is 100% and the single 'limit' parameter is documented in the schema itself, so the baseline of 3 applies. The description adds no information about the limit parameter, such as defaults or maximums, beyond what the schema already provides.

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 gives a specific verb ('Show') and a clearly scoped resource ('newest entries of the log of actions MCP clients took through NVDA'), and enumerates the event types recorded (keys pressed, text typed, windows switched, controls activated). That distinguishes it in substance from nvda_get_log and nvda_get_speech_history, though it never names those siblings explicitly.

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?

There is no explicit when-to-use statement and no routing to alternatives such as nvda_get_log, nvda_trace_events, or nvda_get_output_history, all of which could plausibly be confused with this tool. The only hint is the word 'newest', which implies a recency-review use case but leaves the agent to infer it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds genuine context beyond that: the specific content returned (IAccessible/UIA/IA2 properties, window, Python classes including overlay classes, app module) and its framing as a debugging aid equivalent to NVDA+F1.

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?

Two tight sentences: the first front-loads the resource and enumerates returned content, the second states the use case. No filler, no repetition of the schema.

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?

An output schema exists, so return structure need not be explained, and annotations carry the safety profile; the description is appropriately sized for a simple 2-optional-parameter read tool. The only meaningful gap is disambiguation from sibling inspection tools, which the definition does not address.

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?

Schema description coverage is 100%, so both 'id' (a control from nvda_find_objects) and 'target' (focus vs navigator) are already documented in the schema. The description adds no parameter-level detail beyond 'for a control', so the baseline of 3 applies.

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 names a specific verb+resource: retrieving NVDA's developer info for a control (accessibility API properties, window, Python/overlay classes, app module), and anchors it to a concrete user action (NVDA+F1). It is clear what the tool returns, but it never distinguishes itself from closely related siblings such as nvda_inspect_object, nvda_lookup_api, or nvda_get_navigator_object, which an agent could easily confuse it with.

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?

It gives an implied use case — 'Use it to see which API and NVDAObject class NVDA uses for a control, and why it behaves as it does' — which is a diagnostic/developer intent. However, with 36 sibling tools including inspect_object and lookup_api, there is no explicit when-to-use-this-instead-of-that guidance or exclusion, leaving the agent to infer selection.

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

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

Annotations already declare this read-only, idempotent and non-destructive, so safety is covered. The description adds modest extra value by framing the result as a point-in-time view of the focused control and by offering the unlabeled-control interpretation, but says nothing about behavior when no control has focus or about NVDA needing to be running.

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 identity of the tool and the enumeration of returned fields come first, with usage and the diagnostic tip in a short following paragraph. Every sentence carries information and there is no filler.

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?

An output schema exists and the description's field enumeration complements it well, so return values are well covered. The gap is preconditions for a focus-dependent read (no focused control, NVDA not attached), which an agent would benefit from knowing before calling.

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?

There is a single optional response_format parameter fully documented in the schema, and the description never mentions it. With 100% schema coverage the baseline of 3 applies; the description adds no output-format guidance of its own.

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 gives a specific verb ('describe') and a precisely scoped resource ('the control that has keyboard focus, as NVDA sees it') and enumerates the returned attributes, so the agent knows exactly what it gets. It implicitly separates itself from navigator-object siblings by scoping to keyboard focus, but never names an alternative, keeping it short of a 5.

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?

It provides concrete usage framing: answer "where am I?" or debug an unexpected announcement, plus the heuristic that an unnamed button/link is usually unlabeled. There is no explicit when-not guidance or named alternative (e.g. use nvda_get_navigator_object or nvda_inspect_object when nothing has focus), so it stays at 4.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is narrower and it delivers: entry ordering is stated, and the debug-level precondition is disclosed so the agent understands why results may be empty. It does not discuss truncation behavior from limit or how 'contains' matching performs on large logs, but for a read-only diagnostic that is a small gap.

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?

Two compact sentences, front-loaded with what the tool reads before the diagnostic guidance. No filler words, and the trailing caveat about the debug logging level is the only sentence that could be cut, and it earns its place.

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?

An output schema exists, so return values need not be described, and the description covers purpose, trigger, and a key precondition adequately for a zero-required-parameter read tool. The one missing element is routing guidance against sibling log/inspection tools, which matters given a 36-tool surface.

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?

Schema description coverage is 100% and each parameter (limit, contains, min_level, include_io, response_format) is documented in the schema itself, including defaults and the privacy rationale for include_io. The description adds nothing parameter-specific beyond the indirect allusion to logging level, so the baseline of 3 applies.

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?

States a specific verb and resource ('Read NVDA's log, the one its Log Viewer shows') and pins down ordering ('newest entries last'), which is enough to distinguish it from the action/speech/output history siblings. It stops short of naming those siblings explicitly, so an agent must still infer that nvda_get_action_log is a different artifact.

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?

Gives a concrete use case with a triggering symptom ('after a command did nothing') and a target ('tracebacks from add-ons, app modules or NVDA itself'). It also warns that DEBUG entries only exist when NVDA's logging level is set to debug, which heads off a false negative, but it never contrasts itself with the other log-like tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds useful semantics ('same fields as nvda_get_focus') but says nothing about failure modes, such as what happens when no navigator object exists or NVDA is not running.

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?

One tight sentence with the identifying concept front-loaded and the sibling cross-reference appended; no filler, no restatement of the title.

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?

An output schema exists and annotations cover the safety profile, so the description only needs the conceptual framing, which it delivers clearly. It is slightly thin on how this relates to nearby tools such as nvda_get_object_tree or nvda_inspect_object, but nothing required to call it correctly is missing.

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 single response_format parameter has 100% schema description coverage, so the schema already explains the markdown vs json trade-off; baseline 3 applies. The description contributes nothing additional about parameters, and its 'same fields' remark concerns output rather than input.

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?

Specific verb and resource ('Describe NVDA's navigator object'), with the concept explained as 'the object the user is exploring with object navigation' and explicitly contrasted against keyboard focus. The closing reference to nvda_get_focus lets an agent distinguish it from the closest sibling without opening either schema.

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 clause 'which can differ from the keyboard focus' implicitly tells the agent when this tool is the right one (object-navigation position rather than focus), but there is no explicit when/when-not statement or a direct 'use nvda_get_focus instead if...' routing instruction. Usage is inferable rather than stated.

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

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

Annotations only declare read-only/idempotent/non-destructive; the description adds substantive behavior they cannot: unnamed layout containers are skipped and their children promoted, 'foreground' starts at the web document in browsers/Electron, per-object child lists are capped with a count of omitted items, and the whole tree is cut at max_nodes or after a 3-second budget with a note in the result.

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?

Front-loaded with what is returned, then behavior, then failure recovery, then the alternative tool — a logical progression with no filler sentences. Minor redundancy: the browser/Electron web-document behavior is stated once generally and once in the schema for 'window'.

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?

An output schema exists, and the description still usefully characterizes the outline format and the inline truncation notes an agent will encounter. With 7 parameters, all-optional args, and clear root-selection and budget semantics covered, nothing an agent needs to call this correctly is missing.

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?

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining observable consequences the schema omits — the 3-second time cutoff tied to max_nodes, and the truncation note emitted when max_children clips a list — plus concrete remediation for truncation. It does, however, restate the schema's browser/Electron note for 'window'.

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?

States a concrete verb and resource ("Return the accessibility tree NVDA sees") and even specifies the output shape: an indented outline of role, name, value and states. An agent can distinguish it from survey/inspection siblings like nvda_find_objects or nvda_inspect_object without opening any schema.

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?

Gives positive guidance ("survey a window's layout or find controls that keyboard focus cannot reach"), names the faster alternative for a single-control lookup (nvda_find_objects), and prescribes a recovery path when output is truncated (re-root at a control id or 'focus', or lower max_depth). When-to-use, when-not-to-use and alternatives are all present.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds useful semantics about what the log actually contains (progress-bar beeps, error sounds, browse-mode sounds) and what a speechCanceled entry means. It does not discuss ordering, retention window, or that results are incremental via lastId — though the schema covers the latter.

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?

Two short sentences, front-loaded with the enumeration of output kinds, which is the highest-value information. The closing sentence slightly restates the 'speech was cut off by newer speech' point already made in the first sentence, which is minor redundancy rather than bloat.

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?

With rich annotations, 100% schema coverage, and an output schema, the description only needs to explain what the tool surfaces and why it matters, which it does. The one gap is that it never points at nvda_get_speech_history as the complementary tool, leaving the relationship between the two history tools to inference.

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?

Schema description coverage is 100%, so baseline is 3. The description earns above baseline by explaining what the OutputKind values actually represent in practice — beeps from progress bars and errors, sounds from browse mode and errors — which the bare enum values do not convey. It also motivates include_speech as a way 'to see the whole picture'.

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 states a specific verb and resource ('Show what NVDA put out besides speech') and enumerates the exact event categories captured: beeps, sounds, braille, and speech cancellation. The phrase 'besides speech' implicitly separates it from nvda_get_speech_history, but it never names that sibling explicitly, so an agent must infer the boundary rather than read it.

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?

It gives a concrete diagnostic scenario — 'Speech being cut off is a common cause of "NVDA started to say it and then didn't"' — which tells the agent when this tool is the right choice. It stops short of naming an alternative tool or stating when not to use it, and the decision between this and nvda_get_speech_history (versus the include_speech flag) is left implicit.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description's added value is what matters: it discloses that values reflect the currently active configuration profile rather than stored defaults, and that settings with secret-like names are hidden. That second point is a genuine output-completeness caveat an agent would otherwise misinterpret as missing data.

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?

Two short sentences, front-loaded with what is read and under what conditions, with the parenthetical examples earning their place. The secret-hiding note is a separate sentence placed after the main statement, which is appropriate, though the phrasing is slightly wordy ("Settings whose names suggest secrets, such as an add-on's API key").

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?

With an output schema present, return values need not be described, and the single optional parameter is fully documented in the schema. The description covers the live-configuration semantics and the hidden-secrets caveat, leaving only minor gaps such as whether values are per-profile scoped in the response.

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?

Schema coverage is 100% and the schema already explains the optional `section` parameter, including subsection syntax and the omit-to-list behavior. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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 uses a specific verb and resource ("Read NVDA's settings") and adds scope ("as they apply now, including the active configuration profile"), which is clearly distinct from siblings like nvda_set_value or nvda_get_status. It does not explicitly name a sibling tool it might be confused with, keeping it just below the top mark.

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?

It gives one motivating scenario ("to explain why something is or is not announced") with concrete examples of the settings involved, which implies when to reach for it. However, there is no explicit when-not guidance and no named alternative tool for adjacent needs, so usage is implied rather than directed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds a genuinely non-obvious behavioral fact: speech is captured even when the user has speech turned off, so the history reflects what NVDA would say. It stops short of disclosing buffer capacity, retention, or whether entries are ever dropped.

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?

Two short sentences, front-loaded with the core action and ordering, followed by the one piece of context an agent could not infer. No filler or redundant restatement of the name.

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?

An output schema exists, so return-value explanation is unnecessary, and all four parameters are documented in the schema with annotations covering safety. For a simple read tool the definition is nearly complete; only sibling disambiguation and buffer/retention limits are absent.

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?

Schema description coverage is 100%, so limit, after_id, contains and response_format are all fully documented structurally. The description only restates the id-based polling idea already spelled out in after_id's schema text, adding no new syntax or semantics; baseline 3 applies.

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?

Uses a specific verb and resource ("Return what NVDA has spoken"), plus ordering ("newest last") and the polling affordance. It does not distinguish itself from near-neighbours like nvda_get_output_history, nvda_preview_speech or nvda_wait_for_speech, which an agent must resolve on its own.

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 phrase "with ids for incremental polling" implies the intended usage pattern (poll with after_id to get only new speech), but the description never states when to choose this over nvda_wait_for_speech, nvda_preview_speech or nvda_get_output_history, nor any when-not condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description adds the useful behavioral framing that this is a health/diagnostic probe and that isControlAllowed gates key injection. The one gap is that it doesn't say what happens when NVDA is unreachable, e.g. whether it raises an error or returns a negative status field.

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?

Two short paragraphs, with the core action and the highest-value usage rule front-loaded. The trailing list of JSON field names is somewhat redundant since an output schema exists and costs a line of budget, but it is compact and not padded.

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 zero-parameter diagnostic read with full annotation coverage and an output schema, the description supplies everything needed to decide when to call it. The only shortfall is undocumented failure behavior when NVDA isn't running, which matters for a reachability check.

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 tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter guidance is needed or missing.

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 uses a specific verb (check reachability, report) on a specific resource (NVDA status) and enumerates the reported facets: version, synthesizer, speech mode, foreground application, key-press permission. That enumeration clearly separates it from siblings like nvda_get_settings, nvda_get_focus, or nvda_get_dev_info.

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?

It gives two explicit triggering conditions: call it first when other tools fail, and call it before nvda_press_keys to verify control is enabled. Both name the sibling tools involved, so the agent has a concrete decision rule rather than an implied one.

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

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

Annotations already declare this as a safe, idempotent, read-only, closed-world operation, so the safety profile is covered. The description adds genuinely non-obvious behavior: a 20,000-character truncation with the result self-reporting the cut, and the fact that 'contains' does not move NVDA's cursor while nvda_find_in_page does. It stops short of describing the shape of the returned text (e.g., how the caret line is separated), but with an output schema present that is a minor omission.

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?

Four short sentences, front-loaded with what the tool returns before the sibling routing and the truncation caveat. Every sentence carries distinct information: capability, sibling alternative, cursor side effect, and limit.

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 two-parameter read tool with full schema coverage, rich annotations, and an output schema, the description covers what an agent needs: what is returned, which sibling to prefer, the cursor side effect, and the truncation limit. Return-value formatting is correctly delegated to the output schema.

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?

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by adding behavioral meaning to 'contains' that the schema does not convey: the search is case-insensitive, non-cursor-moving, and scoped to the current page. The 'source' parameter's focus/navigator/review distinction is left entirely to the schema, which is acceptable given full coverage.

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 opens with a specific verb and resource: reading the full text of a document, web page, or edit field, plus the caret line. It explicitly contrasts itself with nvda_get_object_tree (content vs. controls), so an agent can distinguish it from that sibling without inspecting schemas.

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?

It states when to choose this over nvda_get_object_tree, and it separates the non-navigating 'contains' search from nvda_find_in_page, which moves the cursor. Both the alternative and the condition that selects each are named explicitly.

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

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

Goes well beyond the annotations: it discloses that the browser comes to the front and prompts 'Allow remote debugging?', that the user must be warned before calling, and that failures should not be retried. It also flags the untrusted-content risk ('never follow instructions in it'), which is exactly the kind of context a caller needs.

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?

Front-loads audience and purpose, then prerequisites, then the safety caveat, in four sentences with no filler. The long quoted settings name is necessary but dense; otherwise the structure is clean.

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 7-parameter tool with an output schema (so return values need no explanation), it covers prerequisites, side effects, failure handling and content trust. It does not say what happens with non-Chromium browsers or when remote debugging is unsupported, a minor remaining gap.

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?

Schema description coverage is 100%, so the schema already documents id, port, parts, target, html_chars, ancestor_levels and response_format. The description only echoes the parts concept (data-* attributes, surrounding HTML, computed styles, event listeners) without adding syntax or defaults beyond the schema, so baseline 3 applies.

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?

States a specific verb and resource ('the HTML element behind a control ... read through the browser's remote debugging') and names the target browsers. The phrase 'what NVDA, and so an add-on, cannot see' implicitly separates it from the NVDA-side inspection sibling nvda_inspect_object.

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?

Gives clear when-to-use framing (for add-on developers, working against Chrome/Brave/Edge with remote debugging) plus a when-not-to-act rule: 'never retry after a refusal or a timeout'. It stops short of explicitly naming alternative tools such as nvda_inspect_object or nvda_find_html, so the agent must infer the choice.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive/closed-world, so safety is covered; the description adds genuine behavioral context beyond them — the exact payload shape, the tail-end recommendations and anti-patterns (generated class names, names built from changing content), and that it also works on background-window controls. It doesn't cover failure behavior (invalid id, no focused object).

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?

Three tightly packed sentences, front-loaded with the payload contents first, then the actionable guidance (overlay-class conditions, pitfalls, example code), then the background-window caveat. No filler or restatement of the name.

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?

With an output schema present, return format need not be explained, and annotations carry the safety profile; the description nonetheless gives enough about contents and intent for an agent to call it correctly. The only meaningful gap is error/edge-case behavior when the id is invalid or no object exists.

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?

Schema coverage is 100%, so id, target, and response_format are already documented with defaults and enum-like refs. The description adds only marginal meaning — the hint that ids come from nvda_find_objects for background windows — and says nothing extra about choosing focus vs. navigator or markdown vs. json. Baseline 3 applies.

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 names a specific verb (inspect) and resource (a control/object) and enumerates the exact evidence returned: NVDA class, IAccessible2 attributes (tag, id, class, ARIA role, name provenance) or UIA properties, ancestor containers, first children, and virtual-list row counts. That level of specificity clearly separates it from siblings like nvda_get_object_tree or nvda_get_focus, and frames the add-on-development intent.

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?

It gives a clear usage context ('Everything an add-on needs to recognize a control', stable conditions for chooseNVDAObjectOverlayClasses) and a useful cross-reference: to inspect a control in a background window, obtain it via nvda_find_objects with window. It does not explicitly say when to prefer this over nvda_get_object_tree or nvda_get_navigator_object, so no full exclusions are stated.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses two non-obvious behavioral traits: returned ids are short-lived ("Ids are only valid until the next list") and the tool functions in both browse and focus mode. Those are genuine lifecycle and state constraints not present in structured fields. It stops short of describing return shape or how mode affects results, so not a 5.

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?

Three short sentences with the core purpose front-loaded and no padding; the id-lifetime warning is placed after the purpose, which is the right order. Minor awkwardness in the comma-spliced element list, but nothing is wasted.

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?

The tool has only two optional params, full schema coverage, and an output schema, so return values need no explanation. The description covers purpose, ordering, id lifetime, and mode compatibility, which is enough to invoke it correctly; the only minor gap is not clarifying selection against sibling enumeration tools.

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?

Schema description coverage is 100%, so both parameters (type, max_results) are already fully documented with defaults and bounds. The description's enumeration of element kinds loosely mirrors the ElementType enum but adds no new constraint or format detail. Baseline 3 applies when the schema does the heavy lifting.

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 gives a specific verb and resource ("List the headings, links, landmarks, form fields or other elements of the web page or document") plus ordering semantics ("in page order") and an anchoring analogy ("like NVDA's Elements List (NVDA+F7)"). It does not explicitly distinguish itself from close siblings such as nvda_find_in_page, nvda_find_objects, or nvda_get_object_tree, which keeps it from a 5.

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?

Usage context is implied: it references nvda_move_to_element for the returned ids and notes "Works in browse mode and focus mode," which tells the agent the tool is mode-agnostic. However, there is no explicit when-to-use/when-not guidance versus enumeration alternatives like nvda_find_objects or nvda_find_in_page.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: results are scoped to the current focus location, several command sources are merged, and an unbound key is reported as going 'straight to the application' rather than failing.

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?

Two short sentences with the primary behavior front-loaded and no filler. The clause 'like the Input Gestures dialog: NVDA's own, add-ons', the app module's and the focused control's' is slightly list-heavy and reads a bit awkwardly, but every element carries 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?

With an output schema present, return-value detail is unnecessary, and annotations cover safety. The description supplies the focus-scoping caveat and multi-source coverage that an agent needs to interpret results; only minor items like result ordering or whether unassigned commands are included are unstated.

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?

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds meaning by framing 'key' as a mode switch that replaces enumeration with a single lookup and by explaining what the returned answer means when no command is bound, which is not stated in the schema.

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?

States a specific verb and resource ('List the NVDA commands available where focus is now, with their keys') and enumerates the sources covered: NVDA's own, add-ons', the app module's and the focused control's. The alternate lookup mode is also named, so an agent can tell exactly what this tool returns, and no sibling in the list offers anything comparable.

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 explains the two modes (list mode vs. 'With key, say which command a key runs here'), which is genuine mode-selection guidance. However, it never says when to reach for this over related siblings such as nvda_press_keys or nvda_run_script, nor when not to use it; usage is implied rather than stated.

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

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

The annotations already establish a safe, idempotent read. Beyond those, the description discloses the MRU ordering and points to the handle/title as the key to pass onward, which the annotations do not convey (even though the include_hidden schema text carries the hidden-window caveat). It stops short of describing pagination or result size, which is acceptable for a bounded window list.

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?

Two short sentences with zero filler: the core behavior and ordering come first, the follow-up action second. Every clause earns its place.

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?

An output schema exists, so return values need not be described, and both parameters are fully documented in the schema. The description fully covers what to do with the results; only minor gaps exist, such as no hint about the volume of windows returned or how include_hidden changes the listing.

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?

Schema description coverage is 100%, and include_hidden and response_format are both documented in the schema with defaults and rationale. The description adds nothing about either parameter, so it neither compensates for nor detracts from the schema; baseline 3 applies.

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 gives a specific verb and resource ('List the open application windows'), the ordering ('most recently used first'), and the returned content ('application names'). It also names the natural follow-up sibling, so an agent can distinguish it from nvda_activate_window and the inspector tools without reading either schema.

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?

It clearly implies the context of use: enumerate windows and then call nvda_activate_window with the title or handle. It gives no explicit exclusions or when-not guidance, but the routing to the alternative makes the intent unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, but the description adds genuinely new behavior: the full return payload (existence, kind, signature, docstring, members, definition location with source link, deprecation suspicion, close-name suggestions on failure) and the safety clarification that it 'does not run the code it looks at'. That last point is a real disclosure beyond the annotations; minor redundancy with readOnlyHint keeps it from a 5.

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?

Front-loads the audience and the action, then uses a parallel 'With name / With search' structure that maps cleanly onto the two modes. The motivation sentence about annual API churn earns its place by explaining why the tool exists; nothing is padding.

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?

All four parameters have zero required entries, the mutually exclusive modes are explained, and an output schema exists so return-format detail is not strictly needed (the extra summary of returned fields is a bonus). Nothing an agent needs to choose and call this tool correctly is missing.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds the governing semantics the schema only implies: 'With name...' versus 'With search...' as alternative modes with distinct result shapes. The limit and response_format parameters are left to their schema descriptions, which already cover them.

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?

States a specific verb and resource: look up a name in the Python code of the running NVDA instance, targeted at add-on developers. It also distinguishes from sibling runtime tools by scope ('the Python code of the NVDA that is running' plus add-on modules) and by the two lookup modes.

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?

Gives a clear trigger ('before writing add-on code that uses it') and explains why it matters (API breaks in the first release of each year). It also implicitly routes between the name mode and the search mode. It does not explicitly exclude the neighbouring tools such as nvda_inspect_object or nvda_list_scripts, which is the remaining gap.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false. The description adds that activation can follow links or press buttons (consistent with the destructive flag) and that the cursor is first moved and the element read, but it doesn't say what happens with a stale or invalid id, whether focus must be in a document, or what side effects activation may cause beyond the element itself.

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?

One sentence, front-loaded with the primary action and the optional activation branch. No filler, though the trailing 'or activate it' slightly duplicates rather than expands the meaning.

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?

An output schema exists, so return-value explanation is not needed, and the five-parameter timing model is fully covered by the schema. The remaining gap is operational preconditions (browse mode, target window focus, behavior on stale ids) for a tool whose annotations flag destructive, non-idempotent side effects.

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?

Schema description coverage is 100%, so every parameter (id, activate, settle_ms, timeout_ms, until_speech) is already documented in detail, including the default 400ms settle and 3000ms timeout semantics. The description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

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 uses a specific verb and resource ('Move NVDA's browse mode cursor to an element') and ties the input to a named sibling, nvda_list_elements, so an agent knows the source of valid ids. It stops short of distinguishing itself from close siblings like nvda_focus_object and nvda_activate_object, which also move/act on objects.

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?

It implies usage by requiring an id 'from the last nvda_list_elements result' and explains that activate performs the equivalent of Enter in the Elements List. There is no explicit when-to-use versus nvda_focus_object/nvda_activate_object, and no stated prerequisites such as browse mode being active or a document window being focused.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, yet the description still adds substance: this 'sends real input, so it can change or delete things', it requires a user confirmation step, and it documents the two distinct failure codes (controlDisabled vs controlDenied) with different retry behavior. That error and consent semantics are not derivable from the annotations or schema.

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?

Four short sentences, each doing distinct work: capability, risk, confirmation protocol, error handling, and alternative. The risk warning is front-loaded immediately after the purpose, which is the right ordering for a destructive tool.

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 destructive, non-idempotent input-injection tool with 7 parameters, the description covers the safety profile, prerequisite consent, failure modes, and the main sibling alternative. An output schema exists, so return values need no further explanation.

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?

Schema description coverage is 100%, so every parameter (hold, keys, record, settle_ms, timeout_ms, until_speech, record_within) is already documented in the schema with examples and defaults. The description adds no parameter-level detail beyond implying the typing alternative, so the baseline 3 applies.

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 opens with a specific verb and scope: 'Press keys in the active window', and adds the observable outcome ('report what NVDA said and where focus ended up'). That framing lets an agent distinguish it from siblings like nvda_type_text, nvda_run_script, or nvda_activate_window without reading the schema.

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?

It gives explicit when-to-use guidance ('Tell the user what you will press first'), names the alternative for text entry ('To type text, nvda_type_text is faster and does not depend on the keyboard layout'), and states a hard exclusion ('do not retry after controlDenied'). The record parameter also routes event-level tracing to nvda_trace_events, so the agent has a clear decision tree.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses that the scan does not move focus or press keys, that it flags unlabeled or silent controls, and — most usefully — that returned controls get ids consumable by nvda_focus_object, nvda_activate_object, and nvda_get_dev_info. That cross-tool handoff is behavioral context annotations cannot convey.

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?

Two tight paragraphs: the core action and its non-effects come first, the mode behavior and sibling routing follow. Every clause carries information — the parenthetical tool lists are the only density cost, and they are load-bearing for chaining.

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?

With an output schema present, annotations covering the safety profile, and 100% schema coverage on all four parameters, the description only needs to supply routing and chaining context — which it does fully. An agent could call this correctly on the first attempt.

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?

Schema coverage is already 100% with per-parameter descriptions, so the baseline is 3; the description adds genuine meaning by explaining that 'window' includes controls Tab cannot reach and that the scan happens 'at once,' which the schema does not state. It does not add format or interplay detail beyond that.

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 gives a specific verb and resource ('Say what NVDA would announce when each control gets focus') plus two concrete side-behaviors (no focus movement, flag unlabeled/silent controls). It also explicitly contrasts itself with nvda_audit_focus_order, so an agent can separate it from siblings without reading either schema.

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?

It names the alternative tool explicitly and the condition that selects it: 'to test what happens when keys are pressed, use nvda_audit_focus_order.' It also scopes the 'window' mode (whole-window scan including controls Tab cannot reach), leaving no ambiguity about when each mode applies.

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

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

Beyond annotations that only say this is not read-only but not destructive, it discloses the critical side effect that the add-on itself reloads, the bridge restarts on a new port, and calls in the next second may fail. That failure window and the "wait briefly, then check nvda_get_log" recovery instruction are exactly what an agent needs and are found nowhere in the structured fields.

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?

Three short sentences with zero filler: purpose and analogy first, then the surprising side effect, then the mitigation. Front-loading is correct and every clause carries operational weight.

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?

An output schema exists, so return values need no explanation; the description instead spends its budget on the transient failure window and the prerequisite, which are the real risks for this tool. Nothing an agent needs in order to invoke it safely is missing.

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 tool takes no parameters, so there is nothing for the description to disambiguate. Baseline for a zero-parameter schema is 4.

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 gives a specific verb and resource ("Reload global plugins and app modules from disk") and anchors it to a familiar NVDA action (NVDA+control+F3). No sibling tool does anything comparable, so an agent can distinguish it immediately.

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?

It states the motivating scenario ("to try changed add-on code without restarting NVDA") and names a follow-up tool (nvda_get_log) for verifying the outcome, plus a prerequisite matching nvda_press_keys. It stops short of explicitly saying when not to use it or naming alternative recovery paths, but the context is clear.

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

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

Beyond the annotations, it discloses two real behavioral traits: results are state-dependent on the starting window/control, and it requires key-press permission. It does not, however, warn that the run writes to the baseline file (the destructiveHint=true side effect), leaving that to the schema's baseline_file/update_baseline text.

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?

Two short sentences, front-loaded with the purpose and then the critical precondition. Nothing is redundant and no sentence could be dropped without losing meaning.

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 four-parameter tool with an output schema and full schema coverage, the description supplies the essential mental model (regression test, deterministic starting state, permission requirement). The only gap is the baseline-file write behavior, which an agent would otherwise have to infer from the schema.

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?

Schema coverage is 100%, so all four parameters, including the nested ScenarioStep fields and the until_speech semantics, are already documented. The description adds the comparative-baseline framing but no extra detail about parameter syntax or interaction beyond the schema.

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 names a specific verb and resource ('run a scenario of key presses and typing') and states the full outcome: recording NVDA speech and focus after each step and diffing against a saved baseline. It explicitly frames itself as 'an accessibility regression test', which separates it from the single-action siblings nvda_press_keys and nvda_type_text.

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?

It gives a clear usage condition ('Start from the same place each time... or the results will differ') and a prerequisite ('Needs key presses to be allowed, like nvda_press_keys'). It references the sibling primitives but never explicitly says when to choose this tool over chaining nvda_press_keys/nvda_type_text/nvda_wait_for_speech manually.

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

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

The annotations already declare destructiveHint=true and openWorldHint=true, so the mutation risk is covered structurally. The description adds genuinely new behavioral facts: the permission prerequisite, the side effect of reporting NVDA's speech, and the failure mode for key-forwarding commands, which the annotations cannot express.

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?

Three short sentences, front-loaded with purpose before caveats, and every sentence carries a distinct fact (mechanism, key-independence, key-forwarding failure mode, permission requirement). Nothing is redundant.

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?

With an output schema present, return values need not be spelled out, and the description still tells the agent that NVDA's speech is reported. For a destructive, 7-parameter tool it is nearly complete; a brief note on what happens if the script name is not found would close the remaining gap.

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?

Schema description coverage is 100% and the schema already documents every parameter, including cross-tool routing for 'record' (nvda_trace_events) and 'record_within' (ids from nvda_find_objects). The description only adds the notion of the name coming from nvda_list_scripts and of speech being reported, so the baseline 3 is appropriate.

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 opens with a specific verb and resource ('Run an NVDA command by name') and immediately explains the mechanism ('as if its key were pressed, then report what NVDA said'), which separates it from nvda_press_keys and nvda_speak without opening any schema.

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?

It explains the key usage context (works regardless of the user's key bindings) and names a hard precondition ('Needs key presses to be allowed, like nvda_press_keys'), plus a limitation: commands that forward their key to the application cannot work. It does not explicitly say when to prefer nvda_press_keys instead, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered; the description usefully adds the real consequence of browse mode (single letters navigate instead of typing) and the downstream effect on nvda_type_text. It does not, however, explain why the call is flagged destructive or whether setting the same mode twice is a no-op, and 'switch between ... like NVDA+space' slightly suggests a toggle even though an explicit mode is required.

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?

Three short sentences that front-load the core action, then the state-check path, then the typing caveat — no filler. The middle sentence is slightly awkwardly ordered (reporters named before the action they support), but nothing is wasted.

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?

With annotations plus an output schema available, the description supplies what the structured fields cannot: the user-facing effect of each mode and the cross-tool sequencing with nvda_type_text. The only gap is that it does not clarify that mode is a required explicit target (not a toggle) or what the call returns/raises on timeout.

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?

Schema description coverage is 100%, including a fully documented mode enum and the settle_ms/timeout_ms timing knobs, so the schema carries the parameter burden. The description reinforces mode semantics through the 'before nvda_type_text' rule but never mentions the settle/timeout parameters or their behavior, adding little beyond the schema.

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 opens with a specific verb+resource (switch NVDA between browse mode and focus mode) and scopes it to a web page or document, with the 'like NVDA+space' analogy anchoring the exact user-level behavior. It also implicitly differentiates itself from nvda_get_focus and nvda_get_status, which are named as reporters of the mode rather than setters.

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?

It gives an explicit use condition: switch to focus mode before calling nvda_type_text in a web form when NVDA did not switch automatically — a concrete precondition tied to a named sibling. It also routes the agent to nvda_get_focus / nvda_get_status for reading the current mode, so the read/write split is unambiguous.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, but the description adds genuinely non-obvious behavior: the write bypasses the keyboard, it can silently no-op on many web editors, and the caller must verify the reported value. It also classifies the tool as 'controlling the computer', which calibrates agent caution. It stops short of warning that existing text is irrecoverably overwritten, which is the main destructive risk left implicit.

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?

Front-loaded with the experimental mechanism and the mechanism contrast, then the usage caveat, then the safety classification. Almost every sentence earns its place, though the phrase 'found with nvda_find_objects and window' is slightly compressed to the point of ambiguity, and the closing line partially repeats the sibling framing already implied.

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?

With annotations covering the safety profile, an output schema covering the return value, and 100% schema coverage on 7 params, the description only needs to supply the failure model and fallback — which it does. The remaining gap is minor: the record/record_within recording behavior, which can make NVDA silent for seconds, is explained only in the schema, not flagged in the description.

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?

Schema description coverage is 100%, so id, text, record, settle_ms, timeout_ms, until_speech and record_within are all documented in the schema itself. The description adds only indirect meaning for 'id' (that it comes from nvda_find_objects and can be a window) and nothing about record/settle/timeout tuning. Baseline 3 is appropriate when the schema carries the semantics.

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 states a specific verb and resource ('give an edit field new text through its accessibility API') and immediately distinguishes the mechanism from the sibling tool ('instead of the keyboard'), naming UI Automation ValuePattern / IAccessible accValue. It also states the post-condition ('report the value it has now'), so an agent knows both the action and the feedback loop without opening the schema.

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?

Explicit when-to-use is given ('It needs no focus, so it can reach a field in a background window, found with nvda_find_objects and window'), plus an explicit when-it-fails condition (React/Lexical/WhatsApp Web editors) and a named fallback path ('use nvda_focus_object and nvda_type_text'). This is the full when/when-not/alternative triad.

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

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

Annotations only declare the generic safety profile (not read-only, not destructive), so the description's disclosure that output is both spoken aloud and brailled, and that the user perceives every word, is genuinely additive. It stops short of saying whether the call blocks until speech completes or how it interacts with in-flight speech, which matters given the nvda_wait_for_speech sibling.

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?

Two short sentences with the core action front-loaded and the practical constraint second. No filler, and the length warning earns its place because it changes how an agent writes the payload.

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?

An output schema exists, so return values need no explanation, and the description covers purpose, use case, and payload discipline for a two-parameter tool. The remaining gap is the relationship to sibling speech tools (preview vs. real output, blocking vs. async), which an agent still has to infer.

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?

Schema coverage is 100%, so both `text` and `interrupt` are already documented in the schema. 'Keep it short: the user hears every word' reinforces the maxLength intent but adds no syntax or formatting detail beyond what the schema states. Baseline 3 applies.

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?

Specific verb+resource: 'Say a message through NVDA's speech and braille' clearly names the action and the dual output channel (speech + braille). It doesn't explicitly distinguish itself from the sibling nvda_preview_speech, but the 'like an NVDA announcement' framing makes the real-output nature unambiguous.

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?

Gives one concrete use case ('telling the user that a long task finished') but no when-not guidance and no routing to alternatives such as nvda_preview_speech or nvda_wait_for_speech. Usage is implied rather than framed as a decision rule.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the mutation profile is known. The description still adds genuinely new behavior: the clipboard is untouched (unlike paste-based approaches), characters are sent as Unicode so layout is irrelevant, and certain targets silently drop input. It does not say what happens when no control is focused, but the added signal is well above the annotation baseline.

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?

Four short lines, front-loaded with purpose, then prerequisite, then mechanism note, then failure case. Every sentence carries distinct information and none restates the tool name or title.

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?

With an output schema, full annotation coverage and 7 fully described parameters, the description only needs to cover intent, prerequisites and pitfalls, which it does. The one minor gap is not stating the failure mode when nothing is focused or what happens to existing content at the caret position, but the context is otherwise sufficient to call the tool correctly.

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?

Schema description coverage is 100%, so every parameter (record, delay_ms, settle_ms, timeout_ms, until_speech, record_within) is already documented in structured data, setting the baseline at 3. The description contributes only the incidental note that Enter must be pressed separately, matching the text param's single-line constraint, but adds no meaning for the recording or timing parameters.

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?

States a specific verb and resource ('Type text into the focused control') and immediately bounds the mechanism ('as if typed on the keyboard, without touching the clipboard'). This clearly separates it from nvda_set_value (value-setting) and nvda_press_keys (keystroke simulation) without needing the schema.

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?

Gives an explicit prerequisite chain ('Focus an edit field first (nvda_find_objects then nvda_focus_object, or nvda_press_keys)') and an explicit exclusion with the alternative to use instead ('Some games and remote desktop windows ignore this kind of input; use nvda_press_keys there'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description adds genuinely new behavior: it is blocking, it returns a batch of everything said in the meantime, and after_id back-fills speech that predates the call. The one notable omission is what the result looks like when the wait times out with no match, which matters for a blocking polling tool.

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?

Three short sentences: purpose first, return semantics second, the tricky race-condition parameter last. No filler and no repetition of the title.

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?

An output schema exists, so return shape need not be described, and the description covers the blocking semantics and the batching behavior. The only real gap is timeout-expiry behavior for a tool whose core failure mode is 'nothing was said'.

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?

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning the schema lacks: it identifies after_id as the 'lastId from an earlier result', which tells the agent where the value comes from and why to pass it. It does not add anything about contains or timeout_ms beyond the schema.

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 states a specific blocking verb ('Wait until NVDA says something') and concrete triggering events (chat reply, download finishing, dialog opening), and the 'returns as soon as a matching utterance arrives' clause separates it from a passive history read. It never names the obvious sibling alternatives like nvda_get_speech_history or nvda_preview_speech, so the differentiation is inferable rather than explicit.

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 examples give clear situational context for when to call this (waiting on async events), and the after_id note explains the race-condition use case. It stops short of stating when NOT to use it — e.g. that past speech should come from nvda_get_speech_history instead — so an agent must infer the boundary with that sibling.

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