Picture of a control (for developers)

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.